← Back to branch summary

~efargaspro/+junk/codeblocks-16.01-release

« back to all changes in this revision

Viewing changes to src/plugins/contrib/codesnippets/readme.html

  • Committer: damienlmoore at gmail
  • Date: 2016-02-02 02:43:22 UTC
  • Revision ID: damienlmoore@gmail.com-20160202024322-yql5qmtbwdyamdwd
Code::Blocks 16.01

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/plugins/contrib/codesnippets/readme.html
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 
3
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
4
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 
5
<head>
 
6
        <title>Code Snippets Plugin</title>
 
7
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
 
8
</head>
 
9
<body>
 
10
<h1>Code Snippets Plugin</h1>
 
11
 
 
12
<p><ul><li>Arto Jonsson</li><li>Pecan Heber</li><br />
 
13
<a href="http://www.codeblocks.org/">http://www.codeblocks.org/</a></p>
 
14
<br><a href="http://wiki.codeblocks.org/">http://wiki.codeblocks.org/</a></br>
 
15
 
 
16
<h3>Table of contents</h3>
 
17
<ul style="list-style-type: none;">
 
18
        <li>1. <a href="#about">About</a>
 
19
        <ul style="list-style-type: none;">
 
20
                <li>1.1. <a href="#newsnippet">Creating a new snippet</a></li>
 
21
                <li>1.2. <a href="#applysnippet">Applying a snippet</a></li>
 
22
                <li>1.3. <a href="#newCategory">Creating a new Category</a></li>
 
23
                <li>1.4. <a href="#searching">Searching</a></li>
 
24
                <li>1.5. <a href="#File Links">File Link Snippets</a></li>
 
25
        </ul>
 
26
        </li>
 
27
        <li>2. <a href="#development">Development</a>
 
28
        <ul style="list-style-type: none;">
 
29
                <li>2.1. <a href="#todo">Todo</a></li>
 
30
                <li>2.2. <a href="#thecode">About the code</a></li>
 
31
                <li>2.3. <a href="#fileformat">File format</a></li>
 
32
        </ul>
 
33
        </li>
 
34
</ul>
 
35
 
 
36
<hr />
 
37
 
 
38
<h2><a id="about"></a>1. About</h2>
 
39
 
 
40
<p>Code Snippets plugin is a simple Snippets management plugin for
 
41
Code::Blocks. It integrates with the interface by creating a floating
 
42
docking window which shows all the Snippets. Snippets can be assigned to
 
43
Categories or they can be in the global Category called
 
44
<em>All Snippets</em>.</p>
 
45
 
 
46
<h3><a id="newsnippet"></a>1.1. Creating a new Snippet</h3>
 
47
 
 
48
<p>To create a snippet you may
 
49
<ul>
 
50
        <li>1) write the text in the default snippet editor;</li>
 
51
        <li>2) mark some text and drag it over the top of a snippet tree item; or</li>
 
52
        <li>3) cut, paste or drag text into the snippet editor.</li>
 
53
</ul>
 
54
</p>
 
55
 
 
56
<p>For example, create some external text. Select your text and and drag it over
 
57
the top of a Category, either to the <em>All Snippets</em> root item or to some
 
58
other Category you may have created via the Snippets context menu.</p>
 
59
 
 
60
<p>You might noticed that the text you dragged disappeared. This is the default
 
61
behavior of drag and drop; it moves by default. If you want to copy instead,
 
62
simply hold down the <strong>Ctrl</strong> key while dragging the text.</p>
 
63
 
 
64
<p>To assign text to a existing snippet, you drag and drop the text
 
65
to that snippet. If you pefer to append the text, use the context menu <em>Edit</em>
 
66
command.</p>
 
67
 
 
68
<p>
 
69
The default editor is based on Scintilla and contains a context menu of its own
 
70
for copy/cut/paste/undo etc.
 
71
</p>
 
72
 
 
73
<h3><a id="applysnippet"></a>1.2. Applying a Snippet</h3>
 
74
 
 
75
<p>To apply a snippet, double click it. It will be applied to the
 
76
currently active editor at the current cursor location.</p>
 
77
 
 
78
<p>You can, alternatively, right click on the snippet and select <em>Apply</em>.</p>
 
79
 
 
80
<p>You may also open the snippet with the editor, mark the text and drag it to
 
81
its destination.</p>
 
82
 
 
83
<h3><a id="newCategory"></a>1.3. Creating a new Category</h3>
 
84
 
 
85
<p>Snippets can be added to Categories. And Categories can be added to Categories.
 
86
 
 
87
To add a Category, right click the root or other Category and select
 
88
<em>Add SubCategory</em>.</p>
 
89
 
 
90
<p>You may change any Snippet or Category label by slowly left clicking the label,
 
91
typing a new label, then finishing with the <strong>Enter</strong> key.</p>
 
92
 
 
93
<p>Snippet labels may also be changed from within the editor. Right click the
 
94
Snippet, choose <em>Edit</em> and change the Label field, Click <em>Ok</em></p>
 
95
 
 
96
<p>Each Snippet is owned by its containing Category. But you may drag Snippets and
 
97
Categories to other locations on the tree.</p>
 
98
 
 
99
<p>The number of Categories and sub-Categories is not limited.</p>
 
100
 
 
101
<p>Each Category has a parent Category, whose ultimate base is the <em>All Snippets</em>
 
102
parent Category. If you want to create a Category to the root, right click <em>All Snippets</em> and
 
103
select <em>Add SubCategory</em>.</p>
 
104
 
 
105
<h3><a id="searching"></a>1.4. Searching</h3>
 
106
 
 
107
<p>Search for Snippets by typing their labels into the search pane at the
 
108
top of the window. Searching is performed by find-as-you-type method.
 
109
Category labels are included in the default search method.</p>
 
110
 
 
111
<p>Select the <em>">"</em> icon to change the search method and case sensitivity.</p>
 
112
 
 
113
<h3><a id="File Links"></a>1.5. File Link Snippets</h3>
 
114
 
 
115
<p>File Link Snippets contain a file name.</p>
 
116
 
 
117
<p>When the editor is invoked on a File Link Snippet, the file data is opened in the
 
118
editor rather than the Snippet data. The Snippet data containing the file name can
 
119
be accessed with the context menu <em>Properties</em> command.</p>
 
120
 
 
121
<p>To create a File Linked Snippet item either:
 
122
<ul>
 
123
        <li>Right click a text Snippet and invoke the context menu <em>Convert To File Link</em>.</li>
 
124
        <li>Invoke the <em>Properties</em> context menu and choose a file as a target
 
125
        link to be placed in the Snippet item (use the <em>Link Target</em> button).</li>
 
126
</ul>
 
127
Modified data for a File Link is saved with the <em>Ok</em> button and
 
128
disgarded by <em>Cancel</em>.
 
129
</p><p>
 
130
The user may specify their own editor by using the <em>Settings</em> entry in
 
131
the root items context menu.
 
132
</p>
 
133
 
 
134
<h2><a id="development"></a>2. Development</h2>
 
135
 
 
136
<h3><a id="thecode"></a>2.2. About the code</h3>
 
137
 
 
138
<p>Short description of each class used in plugin.</p>
 
139
 
 
140
<h4>CodeSnippets</h4>
 
141
 
 
142
<p><em>CodeSnippets</em> is the main class, subclass of <em>cbPlugin</em>.
 
143
Most of the functionality is not in this class but in
 
144
<em>CodeSnippetsWindow</em>.</p>
 
145
 
 
146
<h4>SnippetItemData</h4>
 
147
 
 
148
<p><em>SnippetItemData</em> is the class which is used in the tree control.
 
149
It holds information about the item type and the actual snippet. The
 
150
class is derived from <em>wxTreeItemData</em>.</p>
 
151
 
 
152
<h4>SnippetsItemTreeCtrl</h4>
 
153
 
 
154
<p><em>SnippetsItemTreeCtrl</em> is the tree control used in the docking
 
155
window. It's subclass of <em>wxTreeCtrl</em> and overloads the OnCompare
 
156
method. The overloaded compare method uses extra checks for Category and
 
157
snippet sorting: Categories are first in the tree, sorted A-Z and then
 
158
the Snippets, sorted A-Z.</p>
 
159
 
 
160
<p>In case you're wondering why the control uses wxWidget's dynamic class
 
161
macros: classes derived from wxTreeCtrl must use these macros so that the
 
162
overloaded <em>OnCompare</em> method is called, see the wxWidgets
 
163
tree control example for more info.</p>
 
164
 
 
165
<h4>CodeSnippetsWindow</h4>
 
166
 
 
167
<p><em>CodeSnippetsWindow</em> is the docking window class and it holds
 
168
most of the functionality of the plugin.</p>
 
169
 
 
170
<h3><a id="fileformat"></a>2.3. File format</h3>
 
171
 
 
172
<p>Code Snippets plugin uses XML (UTF-8 encoded) format to save internal
 
173
text Snippets (text contained in the XML file and designated by the T-folder icon).
 
174
Formats for File Links to external data are user specified (Snippets designated
 
175
by the L-folder icon).</p>
 
176
 
 
177
<p>The XML file starts with root item, named <em>Snippets</em>, which holds all
 
178
the Categories and code Snippets. Code Snippets and Categories use the same
 
179
element called <em>item</em>. The item's attributes indicate what type of item
 
180
it is, Category or code snippet.</p>
 
181
 
 
182
<p><em>Snippets</em></p>
 
183
<ul>
 
184
        <li>Attributes: none</li>
 
185
        <li>Subelements: all code Snippets and Categories</li>
 
186
</ul>
 
187
 
 
188
<p><em>item</em></p>
 
189
<ul>
 
190
        <li>Attributes:
 
191
        <ul>
 
192
                <li>Name -- Name of the element</li>
 
193
                <li>Type -- Type of the element, either "snippet" or
 
194
                "Category".</li>
 
195
        </ul>
 
196
        </li>
 
197
        <li>Subelements:
 
198
        <ul>
 
199
                <li>Snippet -- The actual code snippet (only if the item is type
 
200
                "snippet").</li>
 
201
                <li>Subitems and Categories (only if the item is type
 
202
                "Category").</li>
 
203
        </ul>
 
204
        </li>
 
205
</ul>
 
206
 
 
207
<h4>Example file</h4>
 
208
 
 
209
<blockquote>
 
210
<pre>
 
211
&lt;?xml version="1.0" encoding="UTF-8" standalone="yes" ?&gt;
 
212
&lt;Snippets&gt;
 
213
        &lt;item name="Test Category" type="Category" /&gt;
 
214
                &lt;item name="Test item 1" type="snippet" /&gt;
 
215
                        &lt;snippet&gt;// Test 1&lt;/Snippets&gt;
 
216
                &lt;/item&gt;
 
217
        &lt;/item&gt;
 
218
        &lt;item name="Test item 2" type="snippet" /&gt;
 
219
                &lt;snippet&gt;// Test 2&lt;/Snippets&gt;
 
220
        &lt;item&gt;
 
221
&lt;/Snippets&gt;
 
222
</pre>
 
223
</blockquote>
 
224
 
 
225
<p>The file would create the following structure to the tree control:</p>
 
226
 
 
227
<blockquote>
 
228
<pre>
 
229
All Snippets
 
230
|
 
231
|- Test Category
 
232
|  |
 
233
|  |- Test item 1
 
234
|
 
235
|- Test item 2
 
236
</pre>
 
237
</blockquote>
 
238
 
 
239
</body>
 
240
</html>