| blob | d2ba8969b2e7bb20c01dce63a0f4a0b6ce13c8f1 |
1 <sect2 id="getting-started-starting">
2 <title>Starting &appname;</title>
3 <para>
4 You can start &appname; in the following ways:
5 </para>
6 <variablelist>
7 <varlistentry>
8 <term><guimenu>System</guimenu> menu</term>
9 <listitem>
10 <para>
11 Choose
12 <menuchoice>
13 <guisubmenu>Preferences</guisubmenu>
14 <guisubmenu>Look and Feel</guisubmenu>
15 <guimenuitem>Nautilus-Actions Configuration Tool</guimenuitem>
16 </menuchoice>.
17 </para>
18 </listitem>
19 </varlistentry>
20 <varlistentry>
21 <term>Command line</term>
22 <listitem>
23 <para>
24 To start &appname; from a command line, type the following command:
25 </para>
26 <para>
27 <command><filename>nautilus-actions-config-tool</filename></command>
28 </para>
29 <para>
30 <!-- i18n: "Return" is a key name -->
31 then press <keycap>Return</keycap>.
32 </para>
33 <tip>
34 <para>
35 To view available command line options, type:
36 </para>
37 <para>
38 <command>
39 <filename>nautilus-actions-config-tool</filename>
40 <option>--help-all</option>
41 </command>
42 </para>
43 <para>
44 <!-- i18n: "Return" is a key name -->
45 then press <keycap>Return</keycap>.
46 </para>
47 </tip>
48 </listitem>
49 </varlistentry>
50 </variablelist>
51 </sect2>
53 <sect2 id="getting-started-first-run">
54 <title>The first run</title>
55 <para>
56 When you start &appname;, the following window is displayed.
57 </para>
58 <figure id="nact-FIG-main-empty">
59 <title>&appname; Start Up Window</title>
60 <screenshot>
61 <mediaobject>
62 <imageobject>
63 <imagedata fileref="figures/nact-main-empty.png" format="PNG"/>
64 </imageobject>
65 <textobject>
66 <phrase>
67 Shows &appname; main window.
68 Contains menubar, toolbar, display area,
69 an empty items list in the left, several disabled
70 properties tabs, and statusbar.
71 </phrase>
72 </textobject>
73 <caption>
74 <para>The empty &appname; main window</para>
75 </caption>
76 </mediaobject>
77 </screenshot>
78 </figure>
80 <!-- Include any descriptions of the GUI immediately after the screenshot
81 of the main UI, for example, the items on the menubar and on the toolbar.
82 This section is optional. -->
84 <para>
85 The &appname; main window contains the following elements:
86 </para>
87 <variablelist>
88 <varlistentry>
89 <term>Menubar.</term>
90 <listitem>
91 <para>
92 The menus on the menubar contain all of the commands
93 you need to use in &appname;.
94 </para>
95 <para>
96 Shortcuts are available for some commands:
97 </para>
98 <variablelist>
99 <varlistentry>
100 <term>
101 <keycombo>
102 <keycap>Ctrl</keycap>
103 <keycap>N</keycap>
104 </keycombo>
105 </term>
106 <listitem>
107 <para>
108 Create a new action.
109 </para>
110 </listitem>
111 </varlistentry>
112 <varlistentry>
113 <term>
114 <keycombo>
115 <keycap>Ctrl</keycap>
116 <keycap>S</keycap>
117 </keycombo>
118 </term>
119 <listitem>
120 <para>
121 Save modified actions and menus.
122 </para>
123 </listitem>
124 </varlistentry>
125 <varlistentry>
126 <term>
127 <keycombo>
128 <keycap>Ctrl</keycap>
129 <keycap>Q</keycap>
130 </keycombo>
131 </term>
132 <listitem>
133 <para>
134 Quit the application.
135 </para>
136 </listitem>
137 </varlistentry>
138 <varlistentry>
139 <term>
140 <keycombo>
141 <keycap>Ctrl</keycap>
142 <keycap>X</keycap>
143 </keycombo>
144 </term>
145 <listitem>
146 <para>
147 Cut the current selection, keeping it in the clipboard.
148 </para>
149 </listitem>
150 </varlistentry>
151 <varlistentry>
152 <term>
153 <keycombo>
154 <keycap>Ctrl</keycap>
155 <keycap>C</keycap>
156 </keycombo>
157 </term>
158 <listitem>
159 <para>
160 Copy the current selection to the clipboard.
161 </para>
162 </listitem>
163 </varlistentry>
164 <varlistentry>
165 <term>
166 <keycombo>
167 <keycap>Ctrl</keycap>
168 <keycap>V</keycap>
169 </keycombo>
170 </term>
171 <listitem>
172 <para>
173 Insert the content of the clipboard before the current item.
174 </para>
175 </listitem>
176 </varlistentry>
177 <varlistentry>
178 <term>
179 <keycombo>
180 <keycap>Shift</keycap>
181 <keycap>Ctrl</keycap>
182 <keycap>V</keycap>
183 </keycombo>
184 </term>
185 <listitem>
186 <para>
187 Insert the content of the clipboard as subitem(s) of the current item.
188 </para>
189 </listitem>
190 </varlistentry>
191 <varlistentry>
192 <term>
193 <keycombo>
194 <keycap>Delete</keycap>
195 </keycombo>
196 </term>
197 <listitem>
198 <para>
199 Delete the current selection.
200 </para>
201 </listitem>
202 </varlistentry>
203 <varlistentry>
204 <term>
205 <keycombo>
206 <keycap>F5</keycap>
207 </keycombo>
208 </term>
209 <listitem>
210 <para>
211 Reload the actions and menus.
212 </para>
213 </listitem>
214 </varlistentry>
215 <varlistentry>
216 <term>
217 <keycombo>
218 <keycap>F1</keycap>
219 </keycombo>
220 </term>
221 <listitem>
222 <para>
223 Display the help.
224 </para>
225 </listitem>
226 </varlistentry>
227 </variablelist>
228 </listitem>
229 </varlistentry>
230 <varlistentry>
231 <term>Toolbar.</term>
232 <listitem>
233 <para>
234 Several toolbars may be displayed below the menubar,
235 depending of your choices in the
236 <menuchoice>
237 <guimenu>View</guimenu>
238 <guimenuitem>Toolbars</guimenuitem>
239 </menuchoice> submenu.
240 </para>
241 </listitem>
242 </varlistentry>
243 <varlistentry>
244 <term>Items list.</term>
245 <listitem>
246 <para>
247 The list on the left of the main window contains all items,
248 whether they are actions or menus, currently available for
249 edition in &appname;.
250 </para>
251 <para>
252 Items may be sorted in ascending or descending alphabetical
253 order, or not sorted at all, being directly organized and
254 managed by the user.
255 </para>
256 <para>
257 Invalid items are displayed in red color.
258 </para>
259 <para>
260 Modified items are displayed in italic characters.
261 </para>
262 </listitem>
263 </varlistentry>
264 <varlistentry>
265 <term>Sort buttons</term>
266 <listitem>
267 <para>
268 Three buttons allow you to toggle between sort modes.
269 </para>
270 </listitem>
271 </varlistentry>
272 <varlistentry>
273 <term>Properties tabs.</term>
274 <listitem>
275 <para>
276 The right part of the main window displays all is needed
277 to define how, when and where actions and menus should be
278 displayed.
279 </para>
280 <variablelist>
281 <varlistentry>
282 <term>
283 Action/Menu
284 </term>
285 <listitem>
286 <para>
287 Define in which &nautilus; menus the item should
288 appear, and how it will be displayed.
289 </para>
290 </listitem>
291 </varlistentry>
292 <varlistentry>
293 <term>
294 Command
295 </term>
296 <listitem>
297 <para>
298 Specify which command to execute, and which parameters
299 pass to it.
300 </para>
301 </listitem>
302 </varlistentry>
303 <varlistentry>
304 <term>
305 Execution
306 </term>
307 <listitem>
308 <para>
309 Specify how the command should be executed.
310 </para>
311 </listitem>
312 </varlistentry>
313 <varlistentry>
314 <term>
315 Basenames
316 </term>
317 <listitem>
318 <para>
319 Define the basename filters the &nautilus; selection
320 must satisfy in order the action or menu be candidate
321 for display.
322 </para>
323 </listitem>
324 </varlistentry>
325 <varlistentry>
326 <term>
327 Mimetypes
328 </term>
329 <listitem>
330 <para>
331 Define the mimetype filters the &nautilus; selection
332 must satisfy in order the action or menu be candidate
333 for display.
334 </para>
335 </listitem>
336 </varlistentry>
337 <varlistentry>
338 <term>
339 Folders
340 </term>
341 <listitem>
342 <para>
343 Define the folder filters the &nautilus; selection
344 must satisfy in order the action or menu be candidate
345 for display.
346 </para>
347 </listitem>
348 </varlistentry>
349 <varlistentry>
350 <term>
351 Schemes
352 </term>
353 <listitem>
354 <para>
355 Define the scheme filters the &nautilus; selection
356 must satisfy in order the action or menu be candidate
357 for display.
358 </para>
359 </listitem>
360 </varlistentry>
361 <varlistentry>
362 <term>
363 Capabilities
364 </term>
365 <listitem>
366 <para>
367 Define the capability filters the &nautilus; selection
368 must satisfy in order the action or menu be candidate
369 for display.
370 </para>
371 </listitem>
372 </varlistentry>
373 <varlistentry>
374 <term>
375 Environment
376 </term>
377 <listitem>
378 <para>
379 Define some environment conditions the &nautilus;
380 selection must satisfy in order the action or menu
381 be candidate for display.
382 </para>
383 </listitem>
384 </varlistentry>
385 <varlistentry>
386 <term>
387 Properties
388 </term>
389 <listitem>
390 <para>
391 Display item properties.
392 </para>
393 </listitem>
394 </varlistentry>
395 </variablelist>
396 </listitem>
397 </varlistentry>
398 <varlistentry>
399 <term>Statusbar.</term>
400 <listitem>
401 <para>
402 The statusbar displays some status informations about the
403 currently selected row in the items list.
404 </para>
405 <para>
406 When no relevant information is to be displayed, the
407 statusbar displays the count of loaded menus, actions
408 and profiles.
409 </para>
410 <para>
411 <!-- i18n: "read-only" may be translated -->
412 The «sp;read-only&spraquo; icon
413 <inlinegraphic fileref="figures/read-only.png" />
414 is displayed in
415 the right of the statusbar when appropriate.
416 </para>
417 </listitem>
418 </varlistentry>
419 </variablelist>
420 </sect2>
422 <sect2 id="getting-started-first-action">
423 <title>Creating your first action</title>
424 <para>
425 In this example, we are going to create an action which displays
426 some pretty informations about the current selection.
427 </para>
428 <formalpara>
429 <title>Checking for prerequisites</title>
430 <para>
431 This action will require &zenity;.
432 </para>
433 </formalpara>
434 <para>
435 &zenity; is a program which will allow you to create a graphical
436 user interface from a command-line.
437 </para>
438 <para>
439 You should check that this program
440 is installed on your system, by example by typing the following
441 command in a terminal:
442 </para>
443 <para>
444 <command>
445 <filename>zenity</filename>
446 </command>
447 </para>
448 <para>
449 then press <keycap>Return</keycap>.
450 </para>
451 <formalpara>
452 <title>Creating the action</title>
453 <para>
454 To create a new action, choose
455 <menuchoice>
456 <shortcut>
457 <keycombo>
458 <keycap>Ctrl</keycap>
459 <keycap>N</keycap>
460 </keycombo>
461 </shortcut>
462 <guimenu>File</guimenu>
463 <guisubmenu>New action</guisubmenu>
464 </menuchoice>.
465 </para>
466 </formalpara>
467 <para>
468 A new action is inserted in the items list,
469 and its properties are displayed in the tabs on the right pane.
470 </para>
471 <para>
472 The label of the currently edited action (this one) is added
473 to the application name in the title bar.
474 </para>
475 <figure id="nact-FIG-tab-action">
476 <title>Default properties of a new action</title>
477 <screenshot>
478 <mediaobject>
479 <imageobject>
480 <imagedata fileref="figures/nact-action-tab.png" format="PNG"/>
481 </imageobject>
482 <textobject>
483 <phrase>
484 Shows the default properties of a newly created action.
485 </phrase>
486 </textobject>
487 <caption>
488 <para>Default properties of a new action</para>
489 </caption>
490 </mediaobject>
491 </screenshot>
492 </figure>
493 <para>
494 <!-- i18n: "Items list" is a UI label -->
495 In the <guilabel>Items list</guilabel>, the new action is
496 displayed in italic characters.
497 </para>
498 <para>
499 Italics are used as a reminder that the item has not yet been
500 saved.
501 </para>
502 <para>
503 As another reminder that there is some pending modifications,
504 an asterisk («sp;<literal>*</literal>&spraquo;)
505 comes to prefix the application name in the title bar.
506 </para>
507 <formalpara>
508 <title>Qualifying your new action</title>
509 <para>
510 It merely consists of choosing how your action will be
511 displayed in the file manager context menu.
512 </para>
513 </formalpara>
514 <itemizedlist>
515 <listitem>
516 <para>
517 <!-- i18n: "My first action" is a user entry -->
518 Enter <userinput>My first action</userinput>
519 <!-- i18n: "Context label" is a UI label -->
520 in the <guilabel>Context label</guilabel> entry box.
521 </para>
522 <para>
523 <!-- i18n: "Context label" is a UI label -->
524 The <guilabel>Context label</guilabel> entry box contains
525 the label of the action as you want it to be displayed in
526 the file manager context menu.
527 </para>
528 <para>
529 The label is a mandatory property of your action. If it
530 happens to be empty, then your action will be considered as
531 invalid by &prodname;: it will be displayed in red in
532 <!-- i18n: "Items list" is a UI label -->
533 <guilabel>Items list</guilabel> and will never be candidate
534 to be displayed in the file manager context menus.
535 </para>
536 </listitem>
537 <listitem>
538 <para>
539 Enter <userinput>This will execute an action with some parameters</userinput>
540 <!-- i18n: "Tooltip" is a UI label -->
541 in the <guilabel>Tooltip</guilabel> entry box.
542 </para>
543 <para>
544 <!-- i18n: "Tooltip" is a UI label -->
545 The <guilabel>Tooltip</guilabel> entry box contains the text
546 you want to be displayed as a short help to your action.
547 </para>
548 </listitem>
549 <listitem>
550 <para>
551 Select <inlinegraphic fileref="figures/stock-icon-about.png" />
552 <!-- i18n: "Icon" is a UI label -->
553 in the <guilabel>Icon</guilabel> drop-down list.
554 </para>
555 <para>
556 <!-- i18n: "Icon" is a UI label -->
557 The <guilabel>Icon</guilabel> selection defines the icon
558 which will be associated with your action in file manager
559 context menus and in the toolbar.
560 </para>
561 <para>
562 You have two ways of choosing the icon associated to your
563 action:
564 </para>
565 <itemizedlist>
566 <listitem>
567 <para>
568 <!-- i18n: "Icon" is a UI label -->
569 Click on the <guilabel>Icon</guilabel> drop-down list
570 to select an icon.
571 </para>
572 </listitem>
573 <listitem>
574 <para>
575 Click on <guibutton>Browse</guibutton> to search
576 for an image in the filesystem.
577 </para>
578 </listitem>
579 </itemizedlist>
580 </listitem>
581 </itemizedlist>
582 <formalpara>
583 <title>Specifying the command to be executed</title>
584 <para>
585 When you will select your action in the file manager
586 context menu, this command will be executed, with
587 arguments of your choice.
588 </para>
589 </formalpara>
590 <para>
591 <!-- i18n: "Command" is a UI label -->
592 Click on the <guilabel>Command</guilabel> tab to show the page
593 which will permit you to enter the command.
594 </para>
595 <figure id="nact-FIG-tab-command">
596 <title>Command page</title>
597 <screenshot>
598 <mediaobject>
599 <imageobject>
600 <imagedata fileref="figures/nact-command-tab.png" format="PNG"/>
601 </imageobject>
602 <textobject>
603 <phrase>
604 Shows the Command tab.
605 This tab contains the name of the profile, the command to
606 be executed along with its parameters, and the configuration
607 of the starting working directory.
608 </phrase>
609 </textobject>
610 <caption>
611 <para>Command page</para>
612 </caption>
613 </mediaobject>
614 </screenshot>
615 </figure>
616 <itemizedlist>
617 <listitem>
618 <para>
619 Enter <userinput>zenity</userinput> in the
620 <!-- i18n: "Path" is a UI label -->
621 <guilabel>Path</guilabel> entry box.
622 </para>
623 <para>
624 <!-- i18n: "Path" is a UI label -->
625 The <guilabel>Path</guilabel> entry box defines the command
626 which will be executed when you will select your action in
627 the file manager context menu.
628 </para>
629 <para>
630 You have two ways of defining the command to be executed:
631 </para>
632 <itemizedlist>
633 <listitem>
634 <para>
635 <!-- i18n: "Path" is a UI label -->
636 Enter it in the <guilabel>Path</guilabel> entry box.
637 </para>
638 </listitem>
639 <listitem>
640 <para>
641 Click on <guibutton>Browse</guibutton> to select
642 the executable file on the filesystem.
643 </para>
644 </listitem>
645 </itemizedlist>
646 <para>
647 If the command you enter does not have an absolute path,
648 then it will be searched for in the <envar>PATH</envar>
649 variable at execution time.
650 </para>
651 </listitem>
652 <listitem>
653 <para>
654 <!-- i18n: only "selected item(s)" is translatable -->
655 Enter <userinput>--info --text='%c selected item(s): %U'</userinput>
656 <!-- i18n: "Parameters" is a UI label -->
657 in the <guilabel>Parameters</guilabel>
658 entry box.
659 </para>
660 <para>
661 <!-- i18n: "Parameters" is a UI label -->
662 The <guilabel>Parameters</guilabel> contains the arguments
663 which will be passed to your command when it will be executed.
664 These arguments may embed parameters which will be expanded
665 at runtime.
666 </para>
667 <para>
668 <!-- i18n: "Path" and "Parameters" are UI labels -->
669 If both <guilabel>Path</guilabel> and <guilabel>Parameters</guilabel>
670 are empty, then this action will be considered as invalid:
671 <!-- i18n: "Items list" is a UI label -->
672 it will be displayed in red in <guilabel>Items list</guilabel>
673 and will never be candidate to be displayed in the file
674 manager context menus.
675 </para>
676 </listitem>
677 </itemizedlist>
678 <formalpara>
679 <title>Saving</title>
680 <para>
681 To save all pending modifications, choose
682 <menuchoice>
683 <shortcut>
684 <keycombo>
685 <keycap>Ctrl</keycap>
686 <keycap>S</keycap>
687 </keycombo>
688 </shortcut>
689 <guimenu>File</guimenu>
690 <guisubmenu>Save</guisubmenu>
691 </menuchoice>.
692 </para>
693 </formalpara>
694 <para>
695 &nautilus; automatically takes into account your new action,
696 and displays it in its context menu.
697 </para>
698 <figure id="nact-FIG-start-nautilus-context">
699 <title>Your first action in the &nautilus; context menu</title>
700 <screenshot>
701 <mediaobject>
702 <imageobject>
703 <imagedata fileref="figures/start-context-menu-nautilus.png" format="PNG"/>
704 </imageobject>
705 <textobject>
706 <phrase>Shows the first action in the &nautilus; context menu.
707 </phrase>
708 </textobject>
709 <caption>
710 <para>Your first action in the &nautilus; context menu</para>
711 </caption>
712 </mediaobject>
713 </screenshot>
714 </figure>
715 <para>
716 Cliking of the item in the &nautilus; context menu activates it,
717 and executes the corresponding command.
718 </para>
719 <figure id="nact-FIG-start-zenity">
720 <title>The result of the execution of your first action</title>
721 <screenshot>
722 <mediaobject>
723 <imageobject>
724 <imagedata fileref="figures/start-zenity-result.png" format="PNG"/>
725 </imageobject>
726 <textobject>
727 <phrase>
728 Shows the result of the execution of your first action.
729 This is &zenity; dialog box, displaying the URI of the selected item.
730 </phrase>
731 </textobject>
732 <caption>
733 <para>The result of the execution of your first action</para>
734 </caption>
735 </mediaobject>
736 </screenshot>
737 </figure>
738 </sect2>