See the documentation for each gadget type for information on modifying that type of gadget type. This document exlains many 'special commands' that can be used to modify the GUI in general. It also has some commands that can be used on any gadget type.
Most modify commands are replied to with either 'ok' or 'error'. If more than one gadget parameter is changed by the modify command the reply can be 'ok ok ...' . A reply of a blank line means the modify command was not understood and was ignored.
Modify commands that change gadget parameters begin with 'id GID' Gadgets are modified with the following line format
The parameters allowed depend on the type of gadget that GID refers to.
NOTE: When modifying gadgets on a clicktab page, you should add the page parameter to the modify line.
NOTE: At times you may want to modify a GUI after is is created, but BEFORE the window is opened. Use the 'NoWindow' keyword in the window definition, create the GUI as usual. When you send 'open' the window does NOT open but you do go into modify mode. Modify the GUI then send 'id 0 s 64' to open the window after it has been modified.
Modify Parameters that can be used with all gadgets
(except menu, arexxhost, textattr, commodity...)
------------------------------
page="GID"
Specify the clicktab gadget that controls the page containing the gadget to be modified. Most gadgets seem to modify fine without this being set, but it must be used for string gadgets. It should probably be used when modifying all gadgets on clicktab pages to ensure future compatability.
NOTE: you supply the Gadget ID of the clicktab, NOT the number of the page inside the clicktab.
set
'Set' sets gadget parameters from the supplied tag list. Both 'set' and 'tags' must be used to do this.
tags="tags|data[|tag|data...]|0
A list of tag and value pairs in HEX. Do not forget the trailing null !
Refresh (ref)
Refresh the entire GUI when used alone, or refresh a specific object when used with a GID.
Informational Gadget modify instructions
----------------------------------------
read
Read must not be used with other parameters besides GID.
'id GID read' Reads the gadget specified by GID. The pipe returns the same information as when a user hits a gadget but without the leading 'gadget gid'. In the case of GID=0 read returns the windows 'left top width height' settings.
bounds
Read the size and location of object associated with the GID. This modify command MUST be ' id GID bounds' and returns 'LEFT TOP WIDTH HEIGHT'
address
Read the address of object associated with the GID and information about the gadget type. This modify command MUST be ' id GID address' and returns 'ADDRESS GADGETTYPE'
An address of 0 means no object is associated with the GID.
mouse
Get the position of the pointer. This returns the both the position relative to the window and relative to the screen.
'windowX windowY screenX screenY'
Get="hexvalue"
This special modify command lets you read a value associated with a gadget The pipe replies with 'ok value' when successful, a blank line if it fails.
example 'id 3 get xxxxxxxx'
This reads the selected color in a palette gadget (whose GID is 3).
Gadget interconnection modify
-----------------------------
This function may only be useful to programmers already familiar with interconnection who have registered CA documentation.
Target="gadget_ID" (tar=)
The gadget to be interconnected with.
tags="tagsource|tagdest[|tagsource|tagdest..]|0
The list of tags for interconnection in HEX. Tags must be in pairs, and do not forget the trailing null!
Pointer data is the definition for a pointer. For more information see the intuition call SetPointer(). Pointerdata="" is a special case setting the pointer to a null (invisible) pointer.
specialchar="character" (sc=)
'Character' is a single character that replaces '|', in use as a separator inside parameters like chooserlabels, tags, penmapdata, ...
You should usually use this alone on a modify line, used inside modify commands like add node it will cause an extra 'ok' in the response line.
Quiet (q)
Tell the pipe not to reply to the modify commands. This is actually a toggle switch turning replies off and on. SOME modify commands are ALWAYS replied to. (addnode and getfile selected 0|1)
refresh (ref)
Refresh the gadget referenced by GID. The refresh command can be combined with any other modify command and is always executed last. GID=0 will refresh the windows root layout, this is the best way to refresh all gadgets.
Refresh without a GID specified will refresh the entire window, usually it is better to refresh the root class as described above.
close
Close the CA window. Dispose of window and end the pipe connection to the GUI host.
tick=number
End the modify conversation, Reply with a tick event after number/100 seconds.
Continue (con)
End the modify conversation.
Modifyoff (m)
End the modify conversation AND turn modify off. (do not start any new modify conversations). Note there will be no way to turn modify back on.
Beep=num
Beep the display. If num =0 beep all screens , else beep the GUI's screen.
Bubble Help
------------
Help="num"
If num =0 turn help events off, if num!=0 then turn help events on.
Each GUI can only show one bubble help window at a time.
bubble top=numx left=numy gt="Help Text"
This opens a bubble showing the help text. Top and left are mouse location for the help (as sent to you in the help event you are responding to). Any previous help window will be closed.
'bubble' sent with no parameters will close the bubble with out opening a new one.
Image Functions
----------------
FreeImage="num" fi=
if num=-1 Dispose of a previously defined image without using it. Else free the root bitmap image in buffer num. Be careful not to do this while images still exist that reference this root bitmap.
Draw an image into the gui. Num is the number of the predefined image to be drawn. You MUST set 'top' and 'left' and can also set
target=GID
Reference (clip & offset) drawing to inside the object specified by GID. If target is not given drawing is refrenced to inside the borders of the GUI.
nozz
Make top and left relative to the whole window rather than the inner panel or specified target.
noclip
Allow images to overwrite the entire window, borders and all.
The image number relates to images you have created but not used in your GUI.
For example...
You create an image 'bitmap fn="cat.gif"' it is image 0.
You create another image 'bitmap fn="dog.gif"' it is image 1.
You create another image 'bitmap fn="bird.gif"' it is image 2.
You create a BUTTON using the last image created 'button useimage', the
button used the bird image so it is no longer in the image list.
You create another image 'bitmap fn="frog.gif"' it is image 2.
You now have 3 images available to draw
0 cat
1 dog
2 frog
Drawing images DOES NOT remove images from the image list. Incorporating images directly in your GUI DOES remove images from the image list. The image number is NOT related to the buffer number in the bitmap image parameters.
GID 0
-------
GID 0 is used to specify the GUI window itself. It can be used to control certain aspects of the window. (see window docs)
Defining new gadgets during modify
------------------------------------
define
This causes the current line to be used as a Gadget definition statement rather than modify. You can add or replace gadgets in the already opened window. You may need to send a refresh modify command to make the changes visible.
replace="GID"
The newly defined gadget replaces the existing gadget specified by GID. The pipe tries to free the resources used by the previous gadget right away, but some memory is not freed until the pipe is closed.
WHEN USING REPLACE DO NOT ASSUME WHAT THE RESULTING GID OF THE NEW GADGET WILL BE. The usual sequence of allocated gadget ID's is not followed. Replacing a layout group frees all gadgets in the group as well as the layout itself. Replacing a listbrowser frees its nodes.
You MUST keep track and not try to access gadgets that no longer exist.
It may be better to close the window and open a new one rather than using replace or define. On the other hand some pretty neat thing can be done using define and replace. ;-D
