Contents | Index | < Browse | Browse >
LISTVIEWS
==============================================================
Listviews are very powerfull gadgets. They can take many forms
and have many dedicated commands . This is their template :
> xLISTVIEW L T W H Title Variable File|Dir Offset Mode
where :
Title : is a string that will be placed to the left (by default)
of the listview. Usually you'll give a "" i.e. no title.
Variable : is the variable where the lv's value will be stored.
This "value" varies according to the type of listview:
DIR type LVs will store the file name you clicked on.
NUM type LVs will store the number of the line.
All other types will store the text of the line.
File|Dir : This argument is the name of the file that the LV should
load. When Gui4Cli loads your gui, it will look for this
file, and if it finds it, it will load it.
Listviews will display any kind of file, text or binary.
There is one special kind of text file though that will
be interpreted as a DataBase file. This allows you the
use of %fields and other neat stuff.
You can create a file on the fly if you want, with the
TextFile command. The file can be changed any time with
the LVChange command.
For DIR type LVs this argument is the name of the
directory the LV should open on. You can therafter change
this with the LVDir command.
Offset : LVs can be shifted right/left by clicking on the left
or right quarter of the gadget. This "Offset" argument
specifies the number of characters it should shift.
You can set a 0 value, to disable this feature.
Also, Gui4Cli will automatically move the CURRENT LV
if you use the arrow keys:
- Up/Down/Left/Right arrows - normal movement
- Control key + arrows - Fast movement
- Shift + arrows - go to top,bottom,left,right of document.
Mode : The mode can be NUM, TXT, SHOW, MULTI, or DIR.
This argument defines the LV's type. Listviews come in 3
basic types, according to the last keyword you use :
Normal : (NUM or TXT or SHOW)
-------------------------------
The normal listview is a single-select simple listing of a file.
Example : Run Gui Source
> xListView 10 10 200 100 ListView Var dh0:MyFile 10 TXT
This is a listview which will show the file "dh0:myfile" and when
clicked upon, the Text (TXT or SHOW) of the line you clicked on
will be placed into the "Var" variable. If you had given the NUM
keyword (instead of TXT or SHOW) then the line number of the line
would have been stored into the variable.
The difference between TXT and SHOW, is that SHOW will show you
the selected item i.e. the line clicked on will remain
highlighted, until an other line line is clicked.
Multi-Listviews : (MULTI)
-------------------------
Example : Run Gui Source
This is how a multi-select listview is defined :
> xListView 10 10 200 100 ListView Var dh0:MyFile 10 MULTI
(i.e. change the last keyword) - This kind allows you to make
multiple selections and read them afterwards. This listView will
only "Happen" if the user double-clicks on an item - then this
will be stored into the variable. You can "read" the selected
items at any time.
See the Directory ListView explanation - they both work in the
same way.
Directory Listviews : (DIR)
---------------------------
Example : Run Gui Source
These are File/Dir listers and this is how to get them :
> xListView 10 10 200 100 ListView Var dh0:MyDirectory 10 DIR
These types have more dedicated commands and need more explanation .
DataBase Listviews:
-------------------
NUM,TXT,SHOW and MULTI listviews can also load a special type of
file which will make them into DataBase Listviews .
Database listviews allow you the use of Fields and other goodies.
Understanding ListViews & their Commands :
------------------------------------------
Listviews have the following dedicated commands
Listviews are governed by the notion of CURRENT LISTVIEW and
CURRENT LINE (of the current listview).
The CURRENT LISTVIEW is the one on which all listview commands
will act on.
A ListView becomes current when the user clicks on it. All
listview commands executed thereafter will refer to that
Listview.
The Current ListView can be changed with :
> LVUSE GuiFile GadID
Now, all commands will use the specified listview.
Each listview is made up of a number of lines (or "records").
Commands that act on individual lines (like LVPUT) will act on
the CURRENT LINE of the listview.
The current line is the line that the user last clicked upon,
but that can also be changed to any line you want with the
LVGO command.
More over, commands like LVSEARCH, LVADD etc will change the
CURRENT LINE to the line they return or add etc.
The internal variables $$LV.LINE, $$LV.REC and $$LV.TYPE will
always show you what the CURRENT LINE of the CURRENT LISTVIEW
is. Each listview will keep track of it's own CURRENT LINE,
and remember it throughout it's life.
COLORED TEXT IN LISTIVIEWS :
----------------------------
Starting with V3.2, listviews will interpret ANSI sequences such
as "#27[32mText is now white", and render text in colors or bold
italics etc.
Example : Run Gui Source
And it was a real bitch to get it right, too...
IMAGES IN LISTVIEWS :
---------------------
You can show images anywhere in a listview by stating in the text, at
the place you want the image to appear:
> this is a ESC\MyImage\ test..
(ie Escape-BackSlash-ImageName-Backslash)
(where ESC is the escape char and MyImage is the image's alias)
ie you embed the image name with ESC on one side and again at the
end. Note that the image must already be loaded with the LoadImage
command. Note also that an image can be the height of the line - no
more. If its heigher it will be clipped. You can increase the line
height with the LVLINEDIST attribute.
LISTVIEW ATTRIBUTES :
-----------------------
You can change various things about a listview, using Attributes .
RESIZING Listviews :
--------------------
xLISTVIEW gadgets do not resize properly, because gadtools insists
on limiting their height to a multiple of the font height. I have
added a drawing routine which will fill in the remmaining space at
the bottom with a beveled box.
This can be disabled globally with: SET LVFILL OFF