Using the SashXB GTK extension for user input
The SashXB GTK extension wrappers and exposes all of GTK (The
GIMP Toolkit) to the JavaScript / DHTML developer. This allows you to create
programs with the native look and feel of Gnome without touching a line of
C or C++. Your GTK weblications will use the same theme as your desktop and
will act as native Gnome applications in all respects.
This file will give you a brief reference of the input-related objects
exposed by the SashXB GTK Extension. The "normal" way for you to use them
is through the Glade forms provided by the Sash WDE. You can create your user
interface using the Glade user interface builder, and Sash will handle the
rest for you.
Be sure to look at GTK documentation for details on what function each type of element is appropriate for and how to access and change the data contained in elements. We've documented a few examples below, but there are many other elements at your disposal. Viewing the source for the GTK extension can be overwhelming because there are so many widgets. See the gtk/src/inputs/*.defs files. These are used to generate all of the actual *.idl, *.h, and *.cpp source files.
We've added some additional functionality to a few of the elements, and these are documented at the bottom.
Sash.GTK
Properties
|
readonly long ScreenWidth
|
The width of the screen.
|
readonly long ScreenHeight
|
The height of the screen.
|
Methods
|
void signalConnect(sashIGtkObject obj,
string signalName,
string handlerName,
nsIVariant user_data)
|
Connect a particular signal (specified by the obj
and the signalName) to a Javascript function (specified by handlerName).
|
void signalDisconnect(sashIGtkObject obj,
string signalName)
|
Disconnect all Javascript functions associated with a particular signal (specified by the obj
and the signalName).
|
Example GTK Elements:
1. Sash.GTK.GtkCombo
|
The GtkCombo object represents a drop-down
list with an editing field.
sashIGtkEntry entry
|
A GtkEntry
object representing the text edit box on the top of the
GtkCombo object
|
sashIGtkList list
|
A GtkList object representing
the drop-down portion of the GtkCombo object
|
|
|
2. Sash.GTK.GtkCheckButton and Sash.GTK.GtkRadioButton
The GtkCheckButton
(bottom) and GtkRadioButton (top) represent
the all-familiar check box and radio button respectively.
boolean value
|
A boolean property that indicates
whether the check box / radio button is currently selected.
|
|
|
3. Sash.GTK.GtkEditable
GtkEditable is the parent class for several
important objects, namely
GtkEntry ,
GtkText and
GtkSpinButton . This section
will list their common properties, all of which are implemented in
GtkEditable .
long selection_start_pos
|
This is an integer property that
lets you read / set the starting selection position within the
GtkEditable object.
|
long selection_end_pos
|
This is an integer property that
lets you read / set the ending selection position within the
GtkEditable object.
|
void copyClipboard()
|
Copy the selected ( via
selection_start_pos and selection_end_pos
) contents of the GtkEditable to the clipboard.
Has the same effect as if the user pressed Ctrl-C
|
void pasteClipboard()
|
Overwrite the selected contents
of the GtkEditable with the contents of the clipboard,
or insert them at the current position. Has the same effect as if the user
pressed Ctrl-V
|
void cutClipboard()
|
Copy the selected contents of the
GtkEditable to the clipboard and delete
them. Has the same effect as if the user pressed Ctrl-X
|
void setPosition(long position)
|
Sets the current cursor position
to the integer position
|
long getPosition()
|
Returns the current position of
the cursor as an integer
|
void deleteSelection()
|
Deletes the selected text without
affecting the clipboard
|
void setEditable(boolean isEditable)
|
If isEditable
is set to false, the user will be unable to change the contents
of the GtkEditable in question
|
string getChars(long startPos,
long endPos)
|
Returns a string with the contents
of the GtkEditable object between
startPos and endPos
|
void deleteText(long startPos,
long endPos)
|
Deletes the contents of the
GtkEditable object between startPos
and endPos
|
void selectRegion(long startPos,
long endPos)
|
Selects the contents of the
GtkEditable object between startPos
and endPos. Same as modifying
selection_start_pos and selection_end_pos
|
4. Sash.GTK.GtkEntry
The GtkEntry object represents
a single-line text editing box. It inherits all GtkEditable
functionality, and adds some of its own. It is the parent class for
GtkSpinButton .
string getText()
|
Returns the contents of the
text box as a string
|
void prependText(string text)
|
Inserts the specified
text infront of the contents of the edit box
|
void appendText(string text)
|
Inserts the specified
text after the contents of the edit box
|
void setText(string text)
|
Replaces the contents of
the edit box with text
|
void setMaxLength(long maxLength)
|
Set the maximum allowed length
of text that the user can edit in the box to maxLength
|
|
|
5. Sash.GTK.GtkSpinButton
The GtkSpinButton object
is very similar to a GtkEntry and inherits all of
its functionality. It is useful for input of numeric values and has two increment
/ decrement arrows.
long getValueAsInt()
|
Returns the value of the
text in the spin button box as an integer. It will round down
|
float getValueAsFloat()
|
Returns the value of the
text in the spin button box as a real number
|
void setValue({float, long} numberValue)
|
Sets the numeric value of
the spin box to numberValue. You can change
that value through setText(), too
|
|
|
6. Sash.GTK.GtkText
The GtkText object represents
a multi-line text editing box which inherits all the functionality of
GtkEditable .
string text
|
A string property that represents
the full contents of the edit box
|
void forwardDelete(long
numberOfChars)
|
Delete
numberOfChars characters from the text starting from the current
cursor position
|
void backwardDelete(long numberOfChars)
|
Delete
numberOfChars characters from the text up to the current cursor
position
|
long getLength()
|
Returns the total number
of characters in the edit box
|
void setWordWrap(boolean wrapWords)
|
If
wrapWords is set to true, word wrapping will occur
|
|
|
7. Additional GTK Methods and Properties
In order to make it easier to work with some of the commonly used elements, we've added some properties and methods to the following elements:
GTKCList
This is a GTK columned list, appropriate for displaying structured data (where each element occupies a row and each property occupies a column.
Additional GTKCList Methods
|
long Prepend(array items)
|
Prepend additional items
to the CList.
|
long Append(array items)
|
Append additional items
to the CList.
|
void Insert(long pos,
array items)
|
Insert additional items
to the CList at position pos.
|
string GetText(long row,
long column)
|
Returns the text in a particular cell specified by (row,
column).
|
void RemoveRow(long row)
|
Remove a particular row from the CList.
|
Additional GTKCList Properties
|
readonly array SelectedRows
|
Remove a particular row from the CList.
|
GTKMozEmbed
Use GTKMozEmbed to embed a Mozilla to render HTML.
Additional GTKMozEmbed Methods
|
void Append(string text)
|
Append text to the contents of the embedded Mozilla.
|
Additional GTKMozEmbed Callbacks
|
|
Event
|
Receiver prototype
|
Description
|
OnProgress
|
handler(long curr,
long max)
|
Fired periodically to signal the progress in loading a page. curr is the number of bytes transferred, and max is the total number of byes to be transfered (although it can be somewhat inaccurate).
|
OnLocationChanged
|
handler()
|
Fired when the location is changed.
|
OnLoadBegin
|
handler()
|
Fired when the embedded Mozilla starts loading a page.
|
OnLoadEnd
|
handler()
|
Fired when the embedded Mozilla finishes loading a page.
|
OnTitleChanged
|
handler()
|
Fired when title changes.
|
OnLinkMessageChanged
|
handler()
|
Fired when a link message changes.
|
GTKText
This is also documented above.
Additional GTKText Property
|
string text
|
The text in a text element. Can get or set it.
|
GTKToggleButton
This is also documented above.
Additional GTKToggleButton Property
|
boolean value
|
The value of a toggle element. Can get or set it.
|
GTKWindow
Additional GTKWindow Properties
|
readonly boolean isVisible
|
true if the window is visible.
|
readonly boolean isViewable
|
true if the window is viewable.
|
Additional GTKWindow Methods
|
void raise()
|
Raise the window position to the top of the stacking order.
|
void lower()
|
Lower the window position to the bottom of the stacking order.
|
void move(long x,
long y)
|
Move the Gtk window to the position (x, y) relative to the original position.
.
|
void resize(long width,
long height)
|
Resize the window to the specified dimensions.
|
void move_resize(long x,
long y,
long width,
long height)
|
Move and resize the window.
|
Wing Yung,
Stefan Atev
Last modified: Tue Jun 11 16:48:50 EDT 2002
