-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.htm
1860 lines (1661 loc) · 79.4 KB
/
README.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
ocelotgui A GUI for Tarantool
<P>Version 2.4.0</P>
<P>The ocelotgui GUI, a database client, allows users to connect to
a Tarantool (tm) server, enter SQL statements, and receive results.
Some of its features are: syntax highlighting, user-settable colors
and fonts for each part of the screen, result-set displays
with multi-line rows and resizable columns.</P>
<P>Copyright (c) 2024 by Peter Gulutzan
All rights reserved.</P>
<P>For the GPL license terms see <A href="https://github.com/ocelot-inc/ocelotgui/blob/master/LICENSE.GPL">https://github.com/ocelot-inc/ocelotgui/blob/master/LICENSE.GPL</A>.</P>
<P>This README file has installation instructions, screenshots, and a user manual which has been stripped so it only shows what is relevant for Tarantool.</P>
<H3>Contents</H3><HR>
<H4>Installing</H4>
... <A href="#prerequisites">Prerequisites</A>
... <A href="#getting-the-qt-library">Getting the Qt library</A>
... <A href="#getting-the-libmysqlclientso-library">Getting the libmysqlclient.so library</A>
... <A href="#getting-the-ocelotgui-executable-package">Getting the ocelotgui executable package</A>
... <A href="#starting-the-program">Starting the program</A>
<H4>Illustrating</H4>
... <A href="#some-screenshots">Some screenshots</A>
<H4>Using</H4>
... <A href="#user-manual">User Manual</A>
... <A href="#executive-summary">Executive Summary</A>
... <A href="#the-developer-the-product-and-the-status">The developer, the product, and the status</A>
... <A href="#downloading-installing-and-building">Downloading, installing, and building</A>
... <A href="#starting">Starting</A>
... <A href="#statement-widget">Statement widget</A>
... <A href="#client-statements">Client statements</A>
... <A href="#history-widget">History widget</A>
... <A href="#result-widget">Result widget</A>
... <A href="#menu">Menu</A>
... <A href="#special-effects">Special effects</A>
... <A href="#explorer-widget">Explorer widget</A>
... <A href="#ERDiagram">ERDiagram</A>
... <A href="#charts">Charts</A>
... <A href="#make-menus">Make your own menus</A>
... <A href="#plugins">Make your own plugins/A>
... <A href="#contact">Contact</A>
<H4>Appendixes</H4>
... <A href="#Appendix-1">Appendix 1 Details about ocelotgui options</A>
... <A href="#Appendix-2">Appendix 2 Debugger<A>
... <A href="#Appendix-3">Appendix 3 Tarantool Extras</A>
... <A href="#Appendix-4">Appendix 4 windows</A>
... <A href="#getting-and-using-the-ocelotgui-source">Appendix 5 Getting and using the ocelotgui source</A>
<H3 id="prerequisites">Prerequisites</H3><HR>
<P>The installation instructions in this section are for Linux.
If you prefer to run on Windows, read the installation instructions
in <A href="#Appendix-4">Appendix 4 windows</A>
and come back to read the User Manual section.
The basic prerequisites for installation are Linux, and the Qt library.
</P>
<H3 id="getting-the-qt-library">Getting the Qt library</H3><HR>
<P>You probably will find that the Qt package is already installed,
since other common packages depend on it. If not, your Linux
distro's repositories will provide a Qt package.
For example, on some platforms you can say
"sudo apt-get install libqt5core5a libqt5widgets5" , on others you can say "dnf install qt qt-x11",
on others you can say "dnf install qt5-qtbase qt5-qtbase-gui".</P>
<P>
The Qt version number can be found with <i>find /usr/lib -name "libQt*Gui.so*"</i>, or <i>find /usr/lib64 -name "libQt*Gui.so*"</i>.
If the response starts with libQtGui.so.4 then you have Qt4,
if the response starts with libQt5Gui.so.5 then you have Qt5.
Alternatively it sometimes can be found with qmake -v.
Peter Gulutzan supplies executables only for Qt version 5, but if you have Qt version 4 or Qt version 6 you can build from source.
</P>
<P>The Qt library is necessary for ocelotgui installation.</P>
<H3 id="getting-the-ocelotgui-executable-package">Getting the ocelotgui executable package</H3><HR>
There are ocelotgui binary packages for platforms such as Ubuntu/Mint/MX where "Debian-like" packages
are preferred, or platforms such as Mageia/SUSE/Fedora (but not CentOS 7) where "RPM-like" packages
are preferred.
If one of the following ocelotgui binary packages is compatible with your platform,
cut and paste the corresponding pair of instructions onto your computer and
you can be up and running in about 15 seconds.<BR><BR>
For 32-bit, Debian-like, Qt5<PRE>
wget https://github.com/ocelot-inc/ocelotgui/releases/download/2.4.0/ocelotgui_2.4.0-1_i386.deb
sudo apt install ./ocelotgui_2.4.0-1_i386.deb</PRE>
For 64-bit, Debian-like, Qt5<PRE>
wget https://github.com/ocelot-inc/ocelotgui/releases/download/2.4.0/ocelotgui_2.4.0-1_amd64.deb
sudo apt install ./ocelotgui_2.4.0-1_amd64.deb</PRE>
For 64-bit, RPM-like, Qt5<PRE>
wget https://github.com/ocelot-inc/ocelotgui/releases/download/2.4.0/ocelotgui-2.4.0-1.x86_64.rpm
sudo rpm -i ocelotgui-2.4.0-1.x86_64.rpm</PRE>
For 64-bit, any Linux, Qt5<PRE>
wget https://github.com/ocelot-inc/ocelotgui/releases/download/2.4.0/ocelotgui-2.4.0.tar.gz
tar zxvf ocelotgui-2.4.0.tar.gz
ocelotgui/ocelotgui-qt5</PRE>
For 64-bit, any Linux, Qt4 (deprecated)<PRE>
wget https://github.com/ocelot-inc/ocelotgui/releases/download/2.4.0/ocelotgui-2.4.0.tar.gz
tar zxvf ocelotgui-2.4.0.tar.gz
ocelotgui/ocelotgui-qt4</PRE>
</P>
<H3 id="starting-the-program">Starting the program</H3><HR>
<P>After installing and making sure that ocelotgui is on the
path, start it with<PRE>
ocelotgui --ocelot_dbms=tarantool</PRE>
along with some of many options for example<PRE>
ocelotgui --ocelot_dbms=tarantool --host=localhost --port=3302 --user=guest</PRE>
or<PRE>
ocelotgui --ocelot_dbms=tarantool --host=127.0.0.1 --port=3301 --user=joe --password=secret</PRE>
-- if the program starts, and menu items such as Help|Manual
work, then installation is successful.
Stop again with File|Exit or control-Q.
</P>
<P>Warning: Some menu shortcut keys may not work properly with Ubuntu 14.04.</P>
<H2 ID="some-screenshots">Some screenshots</H2><HR>
<A href="shot1.jpg"><img src="shot1.jpg" alt="shot1.jpg" align="left" height="150"></A>
<A href="shot2.jpg"><img src="shot2.jpg" alt="shot2.jpg" height="150"></A>
<A href="shot3.png"><img src="shot3.png" alt="shot3.png" height="150"></A>
<A href="shot4.jpg"><img src="shot4.jpg" alt="shot4.jpg" height="150"></A>
<A href="shot5.jpg"><img src="shot5.jpg" alt="shot5.jpg" height="150"></A>
<A href="shot6.jpg"><img src="shot6.jpg" alt="shot6.jpg" height="150"></A>
<A href="shot7.jpg"><img src="shot7.jpg" alt="shot7.jpg" height="150"></A>
<A href="shot8.jpg"><img src="shot8.jpg" alt="shot8.jpg" height="150"></A>
<A href="shot9.jpg"><img src="shot9.jpg" alt="shot9.jpg" height="150"></A>
<A href="shot10.jpg"><img src="shot10.jpg" alt="shot10.jpg" height="150"></A>
<A href="shot11.png"><img src="shot11.png" alt="shot11.png" height="150"></A>
<A href="explorer1.png"><img src="explorer1.png" alt="explorer1.png" height="150"></A>
<H2 ID="user-manual">User Manual</H2><HR><HR>
<P>Version 2.4.0, February 15 2024</P>
<P>Copyright (c) 2024 by Peter Gulutzan. All rights reserved.</P>
<P>This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 of the License.</P>
<P>This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.</P>
<P>You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</P>
<H3 id="executive-summary">Executive Summary</H3><HR>
<P>The ocelotgui application, formerly called
'The Ocelot Graphical User Interface', allows users to connect to
a Tarantool DBMS server, enter SQL statements, and receive results.
Some of its features are: syntax highlighting, user-settable colors
and fonts for each part of the screen, and result-set displays
with multi-line rows and resizable columns.</P>
<H3 id="the-developer-the-product-and-the-status">The developer, the product, and the status</H3><HR>
<P>Peter Gulutzan is a Canadian
who has specialized in database products for thirty years,
as an employee of Ocelot Computer Services Inc. and
MySQL AB and Sun Microsystems and Oracle and HP, or as a
contractor for a large company in eastern Europe.</P>
<P>The ocelotgui program is a front end which connects to Tarantool (tm).
In some ways it is like the mysql client program that connects to MySQL or MariaDB servers,
with added GUI features: full-screen editing, syntax
highlighting, tabular display, customized fonts and colors.
It differs from some other front-end GUI products because
it is open source (GPL), it is written in C++, and it makes use
of the Qt multi-platform widget library.</P>
<P>The product status is: stable. It has been known to work as described in
this manual on several Linux distros. It is stable, in the sense that
there are no known severe errors and the features are frozen until the
next version.
Peter Gulutzan will address any bug reports and will answer any questions.</P>
<H3 id="downloading-installing-and-building">Downloading, installing, and building</H3><HR>
<P>To download the product go to
<A HREF="https://github.com/ocelot-inc/ocelotgui">https://github.com/ocelot-inc/ocelotgui</A>.
Instructions for installation will be in the README.md file.
This location may change, or alternate locations may appear.
If so there will either be an announcement on github or on ocelot.ca.</P>
<P>The package contains source code and an executable file named ocelotgui-qt5.</P>
<H3 id="starting">Starting</H3><HR>
<P>
There must be an instance of Tarantool running somewhere.
</P>
<P>
If connection is possible with the tarantoolctl client and does not require
unusual options, then connection is possible with ocelotgui. Options can
be supplied in a special file (usually called ~/.my.cnf) or on a command line.
Therefore the typical
way to start the program is to say
ocelotgui [--option [--option...]]
<br>
For a description of options see <A href="#Appendix-1">Appendix 1 Details about ocelotgui options</A>.
</P>
<P>
<A href="starting-dialog.png"><img src="starting-dialog.png" alt="starting-dialog.png" align="right" height="128"></A>
If a password is required but not supplied, a dialog box will appear.
Or, if the initial attempt to connect fails, an error message will appear
saying it is necessary to choose File|Connect, which will cause the dialog
box to appear. The dialog box has many possible settings
(see the list in <A href="#Appendix-1">Appendix 1</A>);
however, for getting started, the ones that matter most are the ones
at the top: host, port, user, password.
If the connection still fails, then ocelotgui will still come up,
but only non-DBMS tasks such as screen customizing will be possible.
<BR clear="all">
</P>
<P>
<A href="starting.png"><img src="starting.png" alt="starting.png" align="right" height="256"></A>
In any case, an initial screen will appear. After some activity has
taken place, the screen will have four parts, from top to bottom:<BR>
menu <BR>
history widget, where retired statements and diagnostics end up <BR>
results widget, where SELECT result sets appear <BR>
statement widget, where users can type in instructions.<BR>
(And optionally, on the side, an explorer widget.)
Initially, though, only the menu and statement widget will appear.
</P>
<P>
Again, this should be reminiscent of the way a non-GUI client works:
statements are typed at the bottom of the screen, and appear to
scroll off the top after they are executed, with results in the middle.
</P>
<H3 id="statement-widget">Statement widget</H3><HR>
<P>The statement widget is an editable multi-line text box.
The usual control keys that work on other text editors will work
here too; see the later description of Menu Item: Edit.</P>
<P>The program includes a syntax checker and can recognize the parts of
speech in Tarantool grammar.
It will do syntax highlighting
by changing the color, for example comments will appear in light green,
identifiers in green, operators in dark gray, and so on.
The colors can be
customized, see the later description of Menu Item: Settings.</P>
<P>
The left side of the statement widget is reserved for the prompt,
and cannot be typed over. Initially the prompt will be 'tarantool>'
but this can be changed, see the later description of
Client Statements: Prompt.
</P>
<P>
<A href="statement-widget-example.png"><img src="statement-widget-example-tarantool.png" alt="statement-widget-example-tarantool.png" align="right" height="82"></A>
For example, this screenshot shows the statement widget
after the user has changed the default prompt and
entered an SQL statement.
The statement has keywords in magenta, literals in dark green,
operators in light green, and comments in red.
The prompt on the left has a gray background.
<BR clear="all">
</P>
<P>Major Feature Alert: this is not merely a GUI that only will
highlight words that are in a list of keywords.
This GUI will parse the complete Tarantool grammar,
without needing to ask the server. So the highlighting
will be correct, syntax errors will be underlined in red,
and -- since the parsing method is predictive -- there will be
continuous hints about what word is expected next, and
optionally an error message explaining suspected syntax problems
before they go to the server.</P>
<P>Once a statement has been entered and is ready to be executed,
the user can hit control-E, choose menu item Run|Execute, or
place the cursor at the end of the text (after the ';' or other
delimiter) and type Enter. It is legal to enter multiple
statements, separated by semicolons, and then execute them
in a single sequence.</P>
<H3 id="client-statements">Client statements</H3><HR>
<P>A client statement is a statement which changes some behavior
of the client (that is, of the ocelotgui front end) but does not
necessarily go to the Tarantool server. Try out a few: <br>
SET OCELOT_STATEMENT_HIGHLIGHT_KEYWORD_COLOR = 'Fuchsia'; <br>
PROMPT Tarantool \v; <br>
STATUS; <br>
Other interesting ones are DELIMITER (similar to the Tarantool
console's delimiter), SOURCE to read statements from a file,
and EXIT or QUIT.
For example, entering 'quit;'
followed by Enter will cause the program to stop. It is
sometimes not mandatory to end a client statement with ';',
but is strongly recommended.</P>
<P>There are some enhancements affecting the PROMPT statement.
The special sequence '\2' means 'repeat the prompt on all lines',
and the special sequence '\L' means 'show line numbers'. For example,
'PROMPT \2\Tarantool;' will change the prompt so that each line begins
with '[line number] Tarantool>'.</P>
<H3 id="history-widget">History widget</H3><HR>
<P>Once a statement has been executed, a copy of the statement text
and the diagnostic result (for example: 0.04 seconds, OK) will
be placed in the history widget. Everything in the history widget
is editable including the prompt, and it simply fills up so that
after a while the older statements are scrolled off the screen.
Thus its main function is to show what recent statements and
results were. Statements in the history can be retrieved while
the focus is on the statement widget, by selecting 'Previous statement'
or 'Next statement' menu items.</P>
<P>Initially the history widget will show some statements from past
sessions which are stored in a history file.</P>
<H3 id="result-widget">Result widget</H3><HR>
<P>
If a statement is SELECT or PRAGMA or some other statement that
returns a result set, it will appear in the result widget in
the middle area of the screen. The result widget is split up
into columns. Each column has a header and details taken from
what the DBMS returns.
</P>
<P>
The width of the column depends on the result set's definition,
but extremely wide columns will be split onto multiple lines.
That is, one result-set row may take up to five lines.
If the data still is too wide or too tall to fit in the cell,
then the cell will get a vertical scroll bar. The user can
change the width of a column by dragging the column's right
border to the right to make the column wider, or to the left
to make it narrower.
</P>
<P>
The result widget as a whole may have a horizontal and a vertical
scroll bar. The vertical scroll bar moves a row at a time rather
than a pixel at a time -- this makes large result sets more
manageable, but makes the vertical scroll bar unresponsive if
each row has multiple lines and the number of rows is small.
</P>
<P>
For example, this screenshot shows the whole screen after the
user has typed the statement <i>SELECT * FROM "_vindex";</i>
on the statement widget and then executed it. The statement text
has been copied to the history widget, the statement widget has
been cleared, the result widget has the rows.
<BR clear="all">
</P>
<P>
<A href="result-widget-example-tarantool.png"><img src="result-widget-example-tarantool.png" alt="result-widget-example-tarantool.png" height="460"></A>
<BR clear="all">
</P>
<P>
By the way, notice that ocelotgui has "flattened" some maps and arrays in "_vindex".
Flattening is a necessary enhancement for a Tarantool client because otherwise
the result set would not be tabular when selecting from a Lua space.
</P>
<BR><BR>
<H3 id="menu">Menu</H3><HR>
<P>The menu at the top of the screen has File, Edit, Run, Settings,
Options, Debug and Help.</P>
<P>
<A href="menu-file.png"><img src="menu-file.png" alt="menu-file.png" align="right" height="48"></A>
File|Connect, or Ctrl+O, starts the Connect dialog box.
File|Exit, or Ctrl+Q, stops the program.
File|Export brings up a dialog box for exporting selections.
<BR clear="all">
</P>
<P>
<A href="menu-edit-tarantool.png"><img src="menu-edit-tarantool.png" alt="menu-edit-tarantool.png" align="right" height="192"></A>
Edit|Undo or Ctrl+Z, Edit|Redo or Ctrl+Shift+Z, Edit|Cut or Ctrl+X,
Edit|Cut or Ctrl+X, Edit|Copy or Ctrl+C, Edit|Paste or Ctrl+V,
and Edit|Select or Ctrl+A, all work in the conventional manner.
Edit|Redo can only redo the last change.
Previous Statement or Ctrl+P and Next Statement or Ctrl+N will
copy earlier statements from the history widget into the statement
widget, so that they can be edited or re-executed with Run|Execute
or Ctrl+E. Format or Alt+Shift+F changes what is in the statement
widget according to a simple style guide. Autocomplete or Tab will
be discussed later.
<BR clear="all">
</P>
<P>
<A href="menu-run.png"><img src="menu-run.png" alt="menu-run.png" align="right" height="48"></A>
Run|Execute or Ctrl+E or Ctrl+Enter causes execution of whatever is in the
statement widget.
Run|Kill or Ctrl+C tries to stop execution -- this
menu item is disabled for Tarantool.
<BR clear="all">
</P>
<P>
<A href="menu-settings.png"><img src="menu-settings.png" alt="menu-settings.png" align="right" height="120"></A>
Settings|Menu, Settings|History Widget, Settings|Grid Widget,
Settings|Statement, and Settings|Extra Rule 1 are
items which affect the behavior of each
individual widget. The color settings affect foregrounds,
backgrounds, borders, and (for the statement widget only)
the syntax highlights. The font settings affect font family,
boldness, italics, and size.
There may be additional choices affecting appearance,
for example the width of the border used to drag columns
in the result widget.
Settings|Extra Rule 1 is conditional -- for example, to specify
that varbinaries should be displayed as images on a pink background,
set Grid Background Color Pink, set Condition = data_type LIKE
'%BINARY', set Display As = image, then click OK.
<BR clear="all">
</P>
<P>
<A href="menu-options.png"><img src="menu-options.png" alt="menu-options.png" align="right" height="72"></A>
Options|detach history widget,
Options|detach result grid widget,
Options|detach debug widget are
for turning the respective widgets into independent windows,
so that they can be moved away from the statement widget,
or resized. A detached widget is always kept on top of the
other widgets in the application screen. When a widget is
already detached, the menu item text will change to "attached"
and clicking it will put the widget back in its original position.
<BR clear="all">
</P>
<P>
<A href="menu-debug.png"><img src="menu-debug.png" alt="menu-debug.png" align="right" height="132"></A>
The items on the Debug menu are disabled for Tarantool.
<BR clear="all">
</P>
<P>
<A href="menu-help.png"><img src="menu-help.png" alt="menu-help.png" align="right" height="96"></A>
Help|About will show the license and copyright and version.
Help|The Manual will show the contents of README.md (not the manual that you are reading) if README.md is on the same path as
the ocelotgui program; otherwise it will show a copyright, a GPL license, and a pointer to README.md.
Help|libmysqlclient is not relevant for Tarantool.
Help|settings will advise about how to use the Settings menu items.
<BR clear="all">
</P>
<H3 id="special-effects">Special Effects</H3><HR>
<P>
<A href="special-vertical-tarantool.png"><img src="special-vertical-tarantool.png" alt="special-vertical-tarantool.png" align="right" height="256"></A>
> Vertical: If a user starts ocelotgui with the additional option --vertical=1,
> results come up with one column per row.
> (There are other options for displaying as html, raw, etc.).
<BR clear="all">
</P>
<P>
<A href="special-images.png"><img src="special-images.png" alt="special-images.png" align="right" height="256"></A>
Images: If a user chooses Settings | Extra Rule 1 from the menu,
and sets the Condition and Display As boxes as described earlier,
and selects rows which contain VARBINARY columns, and the column values are
images (such as PNG or JPEG or BMP or GIF format data), ocelotgui will display
the result as images.
<BR clear="all">
</P>
<P>
Result-set editing: If a user clicks on a column in the result set
and makes a change, an update statement will appear in the statement widget.
For example, if a result set is the result from SELECT column1, column2 FROM t;,
and the column1 value is 5, and the column2 value is 'ABC', and the user changes
the column2 value to 'AB', then the
statement widget will show UPDATE t SET column2 = 'AB' WHERE column1 = 5 AND column2 = 'AB';.
The user then has the choice of ignoring the update statement or executing it.
</P>
<P>
<A href="special-detach.png"><img src="special-detach.png" alt="special-detach.png" align="right" height="256"></A>
Detaching: If a user chooses Options | detach history widget or
Options | detach result grid widget, then the widget will become a separate window
which can be moved or resized.
<BR clear="all">
</P>
<P id="special-settings">
<A href="special-settings.png"><img src="special-settings.png" alt="special-settings.png" align="right" height="512"></A>
Colors: The Colors and fonts dialog boxes have a simple way to choose
colors, by selecting from a choice of 148 color names / color icons. Users can also
change colors by saying SET object_name_color = color-name | hex-rgb-value.
In fact ocelotgui mixes the modes: for example if a user chooses Settings | Grid Text Color,
then clicks on the 'Red' icon, then clicks OK, ocelotgui generates a
statement "SET ocelot_grid_text_color = 'Red';". This makes the instruction
easy to repeat or put in a script.
<BR clear="all">
</P>
<P>RE: AUTOCOMPLETION. While a user is entering an SQL statement,
ocelotgui will display a list of possible words that may follow.
Hitting the Tab key will cause the first word in the list to be
displayed and accepted.
Users can use arrow keys to select other words,
and can use "set ocelot_shortcut_autocomplete='...'; to choose a different key instead of the Tab key,
and can use "set ocelot_completer_timeout=...'; to choose how many seconds the list will be visible,
and can use "rehash;" to update the list.<br>
<A href="completer_1-tarantool.png"><img src="completer_1-tarantool.png" alt="completer_1-tarantool.png" height="128" width="256"></A><br>
<A href="completer_2-tarantool.png"><img src="completer_2-tarantool.png" alt="completer_2-tarantool.png" height="128" width="256"></A><br>
<A href="completer_3-tarantool.png"><img src="completer_3-tarantool.png" alt="completer_3-tarantool.png" height="128" width="256"></A>
</P>
<P>RE: HINTING FOR COLUMN NAMES. Although hints for syntax appear by
default, hints for table / column identifiers might not. In order to
make identifiers appear on the hint list: (1) ensure the setting
for auto_rehash has not been turned off, and/or (2) enter the statement
"REHASH;" to make the client ask the server for a list of identifiers
in the current database; (3) when entering an SQL statement, type `
(backtick) at the point where an identifier is expected.</P>
<P>RE: FONT. By default, ocelotgui uses a fixed-pitch (mono) font that
has similar attributes to whatever font was in use
at the time it started. This may be a bad choice.
We recommend trying out other fonts with the Settings menu
for each widget.</P>
<P>RE: PERMANENT CUSTOMIZING. Changes to settings can be done
with the Settings menu items, but such changes are not permanent.
So note the commands that ocelotgui performs when settings are
changed, and paste them into a file. Later this file can be
executed (for example with SOURCE file-name), whenever ocelotgui
is started again. Alternatively, settings can be placed in
an options file such as my.cnf.</P>
<P>
<A href="special-settings.png"><img src="conditional.png" alt="special-settings.png" align="right" height="220" width="404"></A>
RE: CONDITIONAL SETTINGS. To override the ordinary <A HREF="#special-settings">settings</A>
for result set displays there is a special SET statement with a WHERE clause:<br>
SET ocelot_grid_setting = string|integer [, ocelot_grid_value = string-or-integer...]<br>
WHERE condition [AND|OR condition ...];<br>
where ocelot_grid_setting is OCELOT_GRID_BACKGROUND_COLOR | OCELOT_GRID_FONT_STYLE | etc.,<br>
and condition has the form item comparison-operator literal, where
item is COLUMN_NAME | COLUMN_NUMBER | COLUMN_TYPE | ROW_NUMBER | VALUE,<br>
and comparison-operator is = | > | >= | < | <= | <> | IS | REGEXP.<br>
For example to say "I want the background color to be pink if
it's in the fourth column of the result set and it's NULL", say<br>
SET ocelot_grid_background_color='pink' WHERE column_number = 4 AND value IS NULL;".</P>
<P>RE: CONNECTION DIALOG. As stated earlier, if a password is necessary
to connect, it is sufficient to start ocelotgui with "--password=<i>password</i>"
or by choosing File|Connect and typing a password in the Password
field (the sixth field in the Connection Dialog Box). Also on the
Connection Dialog Box, if the server is running on the same computer
as the ocelotgui client, it is sometimes a good idea to enter
'127.0.0.1' in the host field, instead of 'localhost'.</P>
<P>RE: HOVERING. Use the mouse to hover over a word in the
statement widget, and ocelotgui will display what kind of word
it is, for example "table identifier".
<A href="hover-tarantool.png"><img src="hover-tarantool.png" alt="hover-tarantool.png" align="right" height="128" width="256"></A>
</P>
<P>RE: FORMAT. Click Edit|Format, and ocelotgui will change the contents of
the statement widget so that keywords are upper case and
sub-clauses or sub-statements are indented.</P>
<P>RE: HISTORY. By default the history does not contain any rows
from result sets of previous statements. To change this, click
Settings|History and enter a number for Max Row Count.
Also users can change the history file name with HISTFILE=name,
change what statements should not go to the ihstory file with HISTIGNORE=regexp,
change whether the history file will include system-generated comments with OCELOT_HISTFILEFLAGS='L'|'LP',
change how large the history file can become with OCELOT_HISTFILESIZE=number,
change how large the initial history can become with OCELOT_HISTSIZE=number.
</P>
<P>RE: EXPORT. A result set can be dumped to a file as text, as table, or as html.
</P>
<P>RE: TARANTOOL EXTRAS. There are a few other Tarantool-specific features
that have to be regarded as "in development" rather than "everyday use".
For example you can enter Lua statements as well as SQL statements.
Read <A HREF="#Appendix-3">Appendix 3 Tarantool Extras</A>.<P>
<H3 id="explorer-widget">Explorer widget</A></H3><HR>
<P>EXPLORER NAME. Explorer.
A similar feature in other GUI clients may be named "object explorer" or "navigator".
Compare the name "Windows explorer".
Note: this section has some MySQL/MariaDB output examples but the feature works with Tarantool too.</P>
<P>EXPLORER SETTINGS.
To change some significant settings, click on the menu bar: Settings|Explorer.<br>
<img src="explorer2.png" alt="explorer2.png" align="right" height="256">
Visible: yes|no. Default no. So if you don't change this to 'yes', it is not visible.
There must be a connection to the DBMS server before it can be made visible.<br>
Sort alphabetically: yes|no. Default no. If 'yes', objects of the same type are sorted alphabetically.<br>
Query: a long select with unions.
The default query selects all databases.
Users can change this query to add WHERE clauses (affects MySQL/MariaDB only).<br>
Detached|Top|Left|Width|Height:
As with other widgets, the explorer is detachable and the explorer's size + position are settable
when it is detached.
Unlike with other widgets, changing width may have an effect even if the explorer is not detached.
The default width depends on the widths of the object names.
</P>
<P>
Ordinarily the explorer widget appears on the left while the other main widgets
(history, grid, statement) appear vertically on the right.
</P>
<P>EXPLORER STYLE. It is a result grid with text columns.
Therefore users get some features without needing to learn anything new:<br>
* ^Find works. (if the item is visible)<br>
* Vertical scroll bar works.<br>
* Settings | Explorer can be used to change colors and font.<br>
* Example: SET ocelot_explorer_text_color='blue' WHERE value = '▶'; REFRESH;<br>
</P>
<P>EXPLORER COLUMNS. There are three text columns.<br>
#1: Min. = Unicode Black Down-Pointing Triangle ▼ or Black Right-Pointing Triangle ▶ if database or table.
If it's a database or table, click on the triangle to hide the parts e.g. columns, or to show them again.
(This is "toggling".)
It's treated as a header item, that is, Result Grid Settings for header affect it.
So ordinarily it has a different background color.<br>
#2: object_type. = S or T or V or C or P or I or E or t<br>
#3: object_name. for example, if object_type='T', this is a table name.<br>
If object_type='C', this is a column name and is taken from part_name.
</P>
<P>EXPLORER ROWS.
Rows are in a hierarchy: S, T or V, C or I, etc.
Within the hierarchy, rows are in order by creation time.
</P>
<P>EXPLORER POSSIBLE USER ACTIONS<br>
Hover. This will show what type of object is under the cursor and contain some short advice.<br>
DoubleClick: This will copy the cell contents to the end of the statement widget<br>
Right Click: puts up a context menu.<br>
Click on the leftmost (Min) column. This will "toggle".
</P>
<P>EXPLORER CONTEXT MENU.
This is the menu that will appear when the user uses the right mouse button to click
over a row in the explorer display.
It is called a context menu because the menu is different for each object type.
For example if it's over a table, then table-related menu items will appear.<br>
Items for all types: Copy to clipboard, Send to SQL editor, Reset, Refresh.<br>
Items for 'S' (Schema): Set as default schema, Filter to this schema, Schema inspector,
Create schema, Alter schema, Drop schema.<br>
Items for 'T' (Table): Select rows, Export dialog - Text, Export dialog - Table,
Export dialog - Html, Import - Text, Create table, Create table like, Drop table, Truncate table.<br>
For 'C' (Column): Show column, Drop column.<br>
For 'I' (Index): Show index, Select index, drop index.<br>
For 'P' (Procedure): Create procedure, Drop procedure.<br>
Details for 'T':
<pre>
Copy to Clipboard Equivalent of "Copy"
Send to SQL editor Copy, then put in statement widget, then execute
Select rows Execute a statement to select 100 rows
Export Dialog - Text Dialog box for export, then do the export if OK
Export Dialog - Table Dialog box for export, then do the export if OK
Export Dialog - Html Dialog box for export, then do the export if OK
Import - Text Generate INSERTs for a file's contents, no options
Create table Generate SHOW CREATE TABLE ...
Create table like Generate CREATE TABLE ... LIKE ...
Drop table Generate DROP TABLE
Truncate table Generate TRUNCATE TABLE
Reset Back to default state with nothing expanded
Refresh Big SELECT to recreate the widget (this can be slow)
</pre>
</P>
<P>EXPLORER EXAMPLE.<br>
<P>
The user makes the explorer visible with Settings|Explorer Widget, it looks like this:<br>
<img src="explorer3.png" alt="explorer3.png" width="300" height="256"><br>
The user clicks the ▶ beside information_schema, it changes to ▼
and the schema items appear:<br>
<img src="explorer4.png" alt="explorer4.png" width="300" height="256"><br>
The user right-clicks on COLLATIONS, and the context menu appears:<br>
<img src="explorer5.png" alt="explorer5.png" width="300" height="256"><br>
The user navigates (with the mouse or the down-arrow key) and selects
(with Enter or Tab or click) the Export dialog - Text choice, and
the export dialog appears:<br>
<img src="explorer6.png" alt="explorer6.png" width="300" height="256"><br>
The user selects the OK button and the contents are dumped to STDOUT:<br>
<img src="explorer7.png" alt="explorer7.png" width="400" height="256"><br>
</P>
<P>EXPLORER SET STATEMENTS.
The user can enter SET statements on the select widget.
Or, some SET statements will be generated when the user clicks OK on the Settings menu.<br>
Keywords are
OCELOT_EXPLORER_ACTION,
OCELOT_EXPLORER_APPLICABLE_DBMSS,
OCELOT_EXPLORER_APPLICABLE_TYPES,
OCELOT_EXPLORER_BACKGROUND_COLOR,
OCELOT_EXPLORER_DETACHED,
OCELOT_EXPLORER_ENABLED,
OCELOT_EXPLORER_FONT_FAMILY,
OCELOT_EXPLORER_FONT_SIZE,
OCELOT_EXPLORER_FONT_STYLE,
OCELOT_EXPLORER_FONT_WEIGHT,
OCELOT_EXPLORER_HEIGHT,
OCELOT_EXPLORER_LEFT,
OCELOT_EXPLORER_SHORTCUT,
OCELOT_EXPLORER_TEXT,
OCELOT_EXPLORER_TEXT_COLOR,
OCELOT_EXPLORER_TOP,
OCELOT_EXPLORER_VISIBLE,
OCELOT_EXPLORER_WIDTH.<br>
The important one is SET ocelot_explorer_visible='yes';<br>
Settings can also be done in the .cnf file or the command line,
for example start ocelotgui with --ocelot_explorer_visible='yes'.<br>
Such statements affect both the explorer widget and its context menu.
Note: some settings changes do not take effect immediately, they are delayed until "Refresh" happens.<br>
</P>
<P>EXPLORER CONDITIONAL SET STATEMENTS.
There is an optional clause ... WHERE VALUE operator 'literal' [{AND|OR} value operator 'literal' ...].
Statements with WHERE clauses affect only rows which match the expression.
Example:<br>
SET ocelot_explorer_background_color='blue' WHERE value > 'p' OR value regexp '1';<br>
<img src="explorer8.png" alt="explorer8.png" height="400"><br>
</P>
<P>EXPLORER REFRESH STATEMENT.
REFRESH is a bit similar to REHASH, but it gets all schemas (databases)
-- so has an effect on the server.
REFRESH is necessary because we don't know when other users might change data definitions.
And it's slow.
Whenever users say REFRESH, the explorer tables are redone.
</P>
<P>EXPLORER IN OPTIONS MENU. Choosing Options|Detach explorer widget,
and rearranging widgets, could result in something like this:<br>
<img src="explorer9.png" alt="explorer9.png" height="400"><br>
</P>
<P>EXPLORER ADVANCED-LEVEL CUSTOMIZING.
As explained earlier, customizing the appearance of the explorer widget
and the context menu, or specific rows on them, is simple
and somewhat like the customizing of the other widgets.
However, one can do more with the context menu -- change the text and
action and shortcut.<br>
Here, for example, is a statement that says
there will be a shortcut associated with the Refresh option:<br>
SET ocelot_explorer_shortcut='Alt+G' WHERE value = 'Refresh';<br>
Here, for example, is a statement that says
"Instead of 'Create table', the 'T' menu choice will be
'Select Count(*)' and the effect, if you click it,
or type the shortcut key, will be that the
statement "SELECT COUNT(*) FROM (table-name-in-context);" will appear on the statement widget,
where it is executed, so the result count appears in the grid widget.<br>
SET ocelot_explorer_action='SELECT COUNT(*) FROM ${object_name};',
ocelot_explorer_text='Customized Selection'
WHERE value = 'Create table';<br>
In other words, users can write their own explorer widgets.<br>
Many of the possible actions can have "macros"
-- strings enclosed inside ${...} that will be replaced when the statement is executed.
Some macros are:
... ${dialog-table} ${dialog_file} ${occurs_text} ${schema_name} ${object_name}
'${object_name}' ${part_name} ${unqualified_part_name} '${part_name}'
${part_type} ${cell} ${clipboard} ${action}.
Since ocelotgui source code is supplied, users can
download it and see the exact effects by reading the C++ statements in program ocelotgui.cpp,
function Context_menu::replacer().<br>
</P>
<H3 id="ERDiagram">ERDiagram</H3><HR>
<P>
<A href="shot2.jpg"><img src="shot2.jpg" alt="shot2.jpg" align="right" height="256"></A>
An entity relationship diagram ("ERDiagram") is a graphic display of tables (in rectangles) and foreign-key relationships
(as lines). The prerequisite is the existence of an explorer widget, that is,<br>
SET ocelot_explorer_visible='yes';<br>
is necessary before requesting an ERDiagram.
An ERDiagram may either be requested from the explorer or from the statement widget.
When it's requested from the statement widget, the syntax is:<br>
SET OCELOT_QUERY = SHOW ERDIAGRAM OF schema_name [COLUMNS PRIMARY] [LINES IN BACKGROUND] [TABLES (table-list];<br>
For example, to get the picture shown here, if you have the well-known "sakila" database, say<br>
SET OCELOT_QUERY = SHOW ERDIAGRAM OF sakila COLUMNS PRIMARY;<br>
</P>
<P>
The optional clause COLUMNS PRIMARY means "show only the columns which are part of a primary key instead of all columns",
the optional clause LINES IN BACKGROUND means "draw lines underneath tables instead of over them",
the optional clause TABLES (table-list) means "show only the tables in this list instead of all tables".
The table list should be a comma-delimited list of table names and each name can be followed by x and y coordinates,
for example "TABLES (customer 0 1, address 1 1" means "display customer in column 0 row 1 and display address in
column 1 row 1".
</P>
<P>
Customize the display fonts and colors with SET OCELOT_GRID_... statements, for example
SET OCELOT_GRID_FONT_WEIGHT='bold' WHERE value REGEXP '_id'; will cause column names which end with _id
(the primary keys) to be displayed with a bold font. Move a mouse over a line to see the foreign key name.
</P>
<H3 id="charts">Charts</H3><HR>
<P>
<A href="shot7.jpg"><img src="shot7.jpg" alt="shot7.jpg" align="right" height="50" width="100"></A>
While a result set is visible, if some columns are numeric, press Alt+Shift+B to
display as a bar chart, Alt+Shift+P to display as a pie chart, Alt+Shift+L to display as a line chart.
No plugins or separate programs are necessary.
But to customize the look of the charts, you will need client statements.
</P>
<P>
The basic statement syntax is<br>
SET ocelot_grid_chart = 'literal' [WHERE clause];<br>
After you've typed SET ocelot_grid_chart = the prompt/autocomplete list wil be
BAR | LINE | PIE | BAR VERTICAL | BAR STACKED | BAR VERTICAL STACKED | BAR SUBGROUP BY VALUE % 3
| BAR SUBGROUP BY LEFT(COLUMN_NAME, 2) | LINE SUBGROUP BY LEFT(COLUMN_NAME, 2) | PIE SUBGROUP BY LEFT(COLUMN_NAME, 2) | [string]
-- and you can make your own combination for example<br>
SET ocelot_grid_chart = 'BAR STACKED SUBGROUP BY VALUE % 5';<br>
The optional WHERE may include COLUMN_NAME | COLUMN_NUMBER | COLUMN_TYPE
(relational operator) (literal value), along with AND|OR, as is usual for
any SET OCELOT_GRID_... statements. For example<br>
SET OCELOT_GRID_chart = 'PIE' WHERE column_name = 'k';<br>
SET ocelot_grid_chart=''; will cancel all previous uses of SET ocelot_chart_grid,
that is, it turns the feature off.
</P>
<P>
Shortcut key combinations are:<br>
Alt+Shift+B causes SET ocelot_grid_chart='bar';<br>
Alt+Shift+L causes SET ocelot_grid_chart='line';<br>
Alt_Shift+P causes SET ocelot_grid_chart='pie';<br>
Alt+Shift+N causes SET ocelot_grid_chart='';<br>
As usual, it is possible to change the key combinations with
SET ocelot_shortcut... statements.
</P>
<P>
GROUPS: Charts make sense when representing numbers.
A "group" is any uninterrupted series of numbers in a result-set row.
For example, in<br>
SELECT 'a',1,2,3.7,4,'b',5e1,6,'c';<br>
the first group is 1,2,3.7,4 and the second group is 5e1,6.
(That is the default. to change the default, use a WHERE clause.)
</P>
<P>SUBGROUPS. A group may be divided into subgroups.
Subgrouping is what decides how sampling is done within a group.
Different methods of subgrouping are appropriate for different
types of chart.<br>
There is automatic subgrouping of pies because otherwise all
pie segments would have a single colour.
(Different subgroups have different colours.)<br>
There is automatic subgrouping of lines because otherwise the
points of all lines would be in the same axis and there would
be no apparent movement. The automatic subgrouping in this case
is SUBGROUP BY LEFT(COLUMN_NAME,2) so it need not be specified.
</P>
<P>
LAYOUT OF A CELL. (After header, not including cell border.)<pre>
+--------------------------------------------------+
| TOP |
|L | L|
|E | CANVAS E|
|F | G|
|T | E|
| | N|
| | D|
| _____________________________________________ |
| BOTTOM |
+--------------------------------------------------+
</pre>
But if cell size is small ocelotgui might cancel everything except the canvas.<br>
CANVAS: is a non-optional component, it has the actual bar/line/pie chart.<br>
LEGEND: is on the RIGHT. Icons and very short text.<br>
TOP: text (not shown by default).<br>
LEFT: For vertical-bar or line has "values axis", for horizontal-bar has "samples axis". Text, rotated 90 degrees.<br>
LEFT LINE: a straight line between LEFT and canvas.<br>
BOTTOM: For horizontal-bar or line has "values axis", for vertical-bar has "samples axis". Text.<br>
BOTTOM LINE: a straight line between canvas and BOTTOM.<br>
Values axis: Becomes next to LEFT or BOTTOM in a bar or line.<br>
Samples axis: Becomes next to LEFT or BOTTOM in a bar or line.<br>
</P>
<P>
It is possible to cancel or change any item except the canvas.
So a fuller statement of the SET syntax can be<pre>
SET ocelot_grid_chart = '
{BAR|LINE|PIE} currently default=bar if this is missing, but don't do it
[VERTICAL] default is horizontal
[STACKED] default is grouping
[TOP=value] default is null
[RIGHT=value|LEGEND|NULL] default is LEGEND
[LEFT=value|DEFAULT|NULL] default is DEFAULT
[BOTTOM=value|DEFAULT|NULL] default is DEFAULT
[AXIS=NULL|ALL] default is ALL, anything but NULL will make axes appear
'
WHERE condition];</pre>
For example, to suppress everything except the canvas with a vertical bar chart:<br>
SET ocelot_grid_chart='BAR VERTICAL RIGHT=NULL LEFT=NULL BOTTOM=NULL AXIS=NULL';<br>
For example, to add a top line along with the other components with a pie:<br>
SET ocelot_grid_chart='PIE TOP=TOPPER';<br>
</P>
<P>
EFFECTS OF OTHER SETTINGS:<br>
SET ocelot_grid_font=... affects what font the text items have.<br>
SET ocelot_grid_cell_border_size=... affects the width of lines.<br>
And other ocelot_grid settings may affect all cells including cells with charts.<br>
Any item value might be truncated. An easy way to change width of a single chart
is to use long column names, that is, instead of saying SELECT 1, 2, 3; say<br>
SELECT 1 AS really_long_column_name, 2, 3;<br>
but for some charts it is possible to use "SET ocelot_grid_cell_width=..." instead.
</P>
<P>
ILLUSTRATIONS. Pictures showing effects are in a blog post:
<a href="http://ocelot.ca/blog/blog/2023/08/08/charts/">Charts</a>.
The current output may look slightly different from the illustrations there,
and the Qwt library is no longer necessary.
<H3 id="make-menus">Make your own menus</H3><HR>
<P>
There are SQL-like statements for manipulating the main menus.
They all begin with SET ocelot_query =, and they are all client statements.
You can execute them without being connected to a DBMS server.<pre>
SET ocelot_query =
SELECT * FROM menus;
SET ocelot_query =
DELETE FROM menus WHERE id = 'id';
SET ocelot_query =
UPDATE menus SET menuitem | shortcut | action = 'literal' WHERE id = 'id';
SET ocelot_query =
INSERT INTO menus VALUES ('id', 'menu-title', 'menu-item', 'action');</pre>
</P>
<P>
SELECT result columns are ID (a unique value which you need to know for the WHERE clause in
other menu statements), MENU_TITLE (the name of a menu), MENU_ITEM (the name of a menu item
within a menu), ACTION (what happens when you select a menu item), SHORTCUT (a keysequence
that does the same thing as selecting the menu item). Initially the ACTION column will have
"[menu]" for a menu, "[separator]" for a line that sometimes is drawn between menu items,
and function names for every menu item. (You would see the same function names if you looked
at the ocelotgui source code.)
</P>
<P>
Suppose you want to remove the File|Exit menu item. You would first use SELECT to see that
the ID is action_file_exit. Then SET ocelot_query = DELETE FROM menus WHERE id = 'action_file_exit';
will remove it. But you could put it back later with SET ocelot_query = INSERT INTO menus
VALUES ('action_file_exit', 'File', 'Exit', 'action_file_exit');.
</P>
<P>
Suppose you want to change the Edit|Cut menu item to Edit|Couper. You would first use SELECT
to find that the ID is action_edit_cut. Then SET ocelot_query = UPDATE menus SET menu_item
= 'Couper' WHERE id = 'action_edit_cut'; will change it. Then you can change the shortcut,
with SET ocelot_query = UPDATE menus SET shortcut = 'Ctrl+Shift+X' WHERE id = 'action_edit_cut';
as described earlier.
</P>
<P>
Suppose you want to make a completely new menu with your own names and actions.
You don't need to insert a "[menu]" row, that will happen automatically when you insert a menu item.
So SET ocelot_query = INSERT INTO menus VALUES ('new_cut', 'NEW', 'Cut!', 'action_edit_cut'); will
make a new menu and a new menu item NEW|Cut! with an action that does the same thing as Edit|cut.
Then SET ocelot_query = INSERT INTO menus VALUES ('new_sql', 'NEW', 'SQL!', 'SELECT 5 AS five, 6 AS six UNION ALL SELECT 5, 6;'); will make a new menu item NEW|SQL! that causes an SQL statement.
So now the menu looks like this:<br>
<img src="menunew.png" alt="menunew.png" width="300" height="140"><br>
So whenever you have stock SQL statements, or a series of SQL statements, that you might want to
repeat frequently, you don't have to store them in a file and read the file with SOURCE. You can
have them in the menu. Just remember: they must end with a semicolon.
</P>
<P>
You can also make a menu whose action is a plugin. Plugins are described in the next section.
</P>
<H3 id="plugins">Make your own plugins</H3><HR>
<P>
A plugin is a routine in a library.
There are SQL-like statements for manipulating the plugins.
They all begin with SET ocelot_query =, and they are all client statements.
You can execute them without being connected to a DBMS server.<pre>
SET ocelot_query =
SELECT * FROM plugins;
SET ocelot_query =
DELETE FROM plugins WHERE action = 'action';
SET ocelot_query =
INSERT INTO plugins VALUES ('library', 'action');</pre>
... where ACTION is the name of the routine in the library.
What the routine does is up to you, you have to write it, in C or C++.
The description here is only about the SQL-like statements.
</P>
Again, SELECT is useful for seeing what plugins have been inserted, and DELETE is useful for undoing.
The INSERT will cause ocelotgui to search for a library (called a .so with Linux or a .dll with Windows),
and within that to search for a routine. There are two kinds of plugins: "trigger plugins" and "menu plugins".
<P>
When ocelotgui reaches one of a certain set of preset points in its code, it calls a
trigger plugin with a structured parameter that contains a lot of information about
state, values of current variables, and permanent settings. The trigger plugin can
act on the information, and in some cases can change it. For example, ocelotgui can call a trigger
plugin whenever it is about to pass an SQL statement to the server, and the plugin can log the
request then change the SQL statement to something completely different.
</P>
<P>
When a menu item has an action that is not one of the 'action_*' routines within the ocelotgui code,
and is not an SQL statement ending with ';', it looks for a menu plugin and calls it. For example,
after SET ocelot_query = INSERT INTO plugins VALUES ('/home/pgulutzan/plugin/libplugin.so', 'menu_action');
and after SET ocelot_query = INSERT INTO menus VALUES ('menu_action', 'NEW', 'The Example', 'menu_action');
and after SET ocelot_query = UPDATE menus SET shortcut = 'Shift+F12' WHERE id = 'menu_action';
and after the user either clicks the NEW/The Example menu item or types Shift+F12, the menu_action
function in libplugin.so will run.