NOTE:
This project is no longer being maintained: it was developed for my masters thesis, which was completed in early 1997. I still, however, welcome any questions or comments that people may have.

[Home] [ToC] [Prev] [Next]

iHTML Python Language

Standard ihEvent Module

The ihEvent module exposes the basic mechanisms of Interactive HTML's event-handling system, and adds some higher-level functionality to them.

Exported Values

Name Spaces

ClassNames


	    NameSpace

of the currently defined event classes. It is initialized with the following names:

Document: A document-level event.
Widget: A widget-level event.
Null: An empty event.

CodeNames


	    NameSpace

of the currently defined event codes. It is initialized with the following names:

Any: A generic event. All attribute values are undefined.
Displayed: A view has been displayed. No event attributes are defined.
Enter: The pointer has entered a user interface area. The event attributes defined for this code are:
KeyState, MouseState, MouseX, and MouseY.
HitAnchor: The user has selected a hypertext link. The event attributes defined for this code are:
AnchorName.
KeyPress: The user has pressed a key on the keyboard, or the key has been held down and is repeating. The event attributes defined for this code are:
KeyASCII, KeyState, MouseState, MouseX, and MouseY.
KeyRelease: The user has released a key that had been pressed on the keyboard. The event attributes defined for this code are:
KeyASCII, KeyState, MouseState, MouseX, and MouseY.
Leave: The pointer has left a user interface area. The event attributes defined for this code are:
KeyState, MouseState, MouseX, and MouseY.
Loaded: A data request has completed. No event attributes are defined.
MouseMove: The pointer position has changed. The event attributes defined for this code are:
KeyState, MouseState, MouseX, and MouseY.
MousePress: The user has pressed one of the mouse buttons. The event attributes defined for this code are:
KeyState, MouseButton, MouseState, MouseX, and MouseY.
MouseRelease: The user has released on of the mouse buttons. The event attributes defined for this code are:
KeyState, MouseButton, MouseState, MouseX, and MouseY.
OffAnchor: The mouse pointer has moved off a hypertext link. The event attributes defined for this code are:
AnchorName.
OnAnchor: The mouse pointer has moved over a hypertext link. The event attributes defined for this code are:
AnchorName.
Print: The document has been printed. No event attributes are defined.
Resize: A user interface area has changed size. The event attributes defined for this code are:
RedrawHeight, RedrawX, RedrawY, and RedrawWidth.
Redraw: A user interface area has changed or been exposed, and needs to be redrawn. The event attributes defined for this code are:
RedrawHeight, RedrawX, RedrawY, and RedrawWidth.
Scroll: A view into a larger area has scrolled or otherwise been changed. The event attributes defined for this code are:
KeyState, MouseState, ViewBottom, ViewFullHeight, ViewFullWidth, ViewHight, ViewLeft, ViewRight, ViewTop, and ViewWidth.

These two name spaces are used to manage event class and code types. They are accessed as dictionary, with the key being the name desired; the returned value is an object that can be compared for equality with other names.

For example a line in an event handler to check for MousePress events would be:

if( event.Code == ihEvent.CodeNames['MousePress'] ):
    # Do something fantastic.

New codes are created simply by accessing other keys in the dictionary. For example:

class my_widget(ihWidget.Widget):

    ...

    def send_my_event(self):
        event = NewEvent(self._Document_,
                         ihEvent.ClassNames['Widget'],
                         ihEvent.CodeNames['my_event'],
                         None)
        HandleEvent(event)

    ...

    def OnEvent(self, event):
        if( event.Code == ihEvent.CodeNames['my_event'] ):
            # Do something even more fantastic.

Because comparisons of these identifier objects is very fast, a program will typically retrieve them from the NameSpace when it initializes, and cache them for later use:

class my_widget(ihWidget.Widget):

    def __init__(self, ***args):

        apply(ihWidget.Widget.__init__,(self,),args)

        self.my_event = ihEvent.CodeNames['my_event']
        self.myMousePress = ihEvent.CodeNames['MousePress']

    ...

    def send_my_event(self):
        event = NewEvent(self._Document_, ihEvent.ClassNames['Widget'],
                         self.my_event, None)
        HandleEvent(event)

    ...

    def OnEvent(self, event):
        if( event.Code == self.my_event ):
            # Do something even more fantastic.
        elif( event.Code == self.myMousePress ):
            # Your brain implodes.

Exported Exceptions

There are no global exceptions defined by this module.

Exported Functions

NewEvent

Synopsis

NewEvent(doc,
	    class, code, object)

Arguments

doc: The Document class instance of the document this program is executing inside.
class: The new event's class, from ClassNames.
code: The new event's code, from CodeNames.
Object: Any arbitrary object that this event is from, or None.

Result

A brand new Event object.

This function creates a new Event object, that can be used to send information about events in the system. The returned event is initialized with the given parameters, which can not be changed for the life of the object.

Exported Types

`Event`

This type encapsulates the information related to a single user-interface event.

Methods

No methods are defined by this type.

Members

AnchorName

A string representing the text of a hypertext anchor in a document. This is the text exactly as it appears in a HREF attribute.

Class

Read-only. A class ID from the ClassNames name space that identifies this event's major class type.

Code

Read-only. A class ID from the CodeNames name space that identifies this event's minor code type.

Document

Read-only. The


	      Document

in which this event occurred.

KeyASCII

An integer representing the ASCII keycode associated with the event. Currently, non-ASCII keys (e.g., cursor keys, function keys, etc.) are not defined.

KeyState

An integer representing the key modifiers that were down when this event occurred. Individual bits in the integer represent the keys -- if a bit is set, then the associated key is down. The currently defined bits are:

0 (mask: $01): "Shift" key.
1 (mask: $02): "Control" key.
2 (mask: $04): "Caps-lock" key.
3 (mask: $08): "Alt" key.

MouseButton

An integer indicating the button that caused the event. The possible values are:

0: "Select" button.
1: "Popup" button.
2: "Option" button.

MouseState

An integer representing the mouse buttons that were down when this event occurred. Individual bits in the integer represent the buttons -- if a bit is set, then the associated button is down. The currently defined bits are:

0 (mask: $01): "Select" button.
1 (mask: $02): "Popup" button.
2 (mask: $04): "Option" button.

MouseX

An integer representing the current X pixel location of the pointer, usually relative the the Object that produced the event.

MouseY

An integer representing the current Y pixel location of the pointer, usually relative the the Object that produced the event.

Object

Read-only. The object that produced this event. Typically a


	      Widget

instance, but this can be any Python object or the None symbol.

RedrawHeight

An integer representing the pixel height of either: (a) the display region that needs to be redrawn, if this is a Redraw event; or (b) the new size of the object, if this is a Resize event.

RedrawWidth

An integer representing the pixel width of either: (a) the display region that needs to be redrawn, if this is a Redraw event; or (b) the new size of the object, if this is a Resize event.

RedrawX

An integer representing the left edge of either: (a) the display region that needs to be redrawn, if this is a Redraw event; or (b) the new position of the object, if this is a Resize event.

RedrawY

An integer representing the top edge of either: (a) the display region that needs to be redrawn, if this is a Redraw event; or (b) the new position of the object, if this is a Resize event.

ViewBottom

This member variable is only valid for Document events.
An integer representing the bottom edge of the visible portion of a view into a larger display area. I.e., this is the current bottom position of the view on the entire HTML document.

ViewFullHeight

This member variable is only valid for Document events.
An integer representing the total height of a display area, of which only a narrower section may be visible.

ViewFullWidth

This member variable is only valid for Document events.
An integer representing the total width of a display area, of which only a narrower section may be visible.

ViewHeight

This member variable is only valid for Document events.
An integer representing the height of the visible portion of a view into a larger display area. I.e., this is the height of the window's sub-view on the entire HTML document.

ViewLeft

This member variable is only valid for Document events.
An integer representing the left edge of the visible portion of a view into a larger display area. I.e., this is the current left position of the view on the entire HTML document.

ViewRight

This member variable is only valid for Document events.
An integer representing the right edge of the visible portion of a view into a larger display area. I.e., this is the current right position of the view on the entire HTML document.

ViewTop

This member variable is only valid for Document events.
An integer representing the top edge of the visible portion of a view into a larger display area. I.e., this is the current top position of the view on the entire HTML document.

ViewWidth

This member variable is only valid for Document events.
An integer representing the width of the visible portion of a view into a larger display area. I.e., this is the width of the window's sub-view on the entire HTML document.

Description

This type represents a single user-interface event that has occurred in the system. This event may either be a low-level event, generated by the user (for example, a mouse button press, keyboard key, etc.) or a higher-level event, such as a menu selection, generated indirectly by program components. In either case, every event is tagged with two identifier variables, that combine to describe the type of event this is

The Class is the broad category of the event. Two of these are currently defined: the Document class is for events that occur as part of the over-all document, such as scrolling its view, pressing anchors, printing, etc.; the Widget class is for events that occur as part of an application's user interface elements, such as button presses, keyboard events, mouse movement, etc.
The Code is the actual type of action that occurred. This is used to indicate which of the specific examples above happened: the view changing, printing, button press, etc.

In addition to these two, the event has two other immutable member variables. The Document is the overall document in which this event has occurred, and the Object is the object that generated the event, such as a Widget.

The rest of this type's member variables provide more detailed information about the event that happened. While the ones listed above are the standard ones used by the iHTML system, the programmer is free to add any custom values that are desires. This is done as any other attribute is set, for example:

event = ihEvent.NewEvent(_Document_,
                         ihEvent.ClassNames['Widget'],
                         ihEvent.CodeNames['custom_code'],
                         None)
event.custom_data = "This is my own data."
HandleEvent(event)

These additional values will then travel along with the event, just as the core values do. There is one important limitation to this, however, if the event moves between program contexts (e.g., from an applet to the document, or from one applet to another), any additional values attached to the event that are not described above will be lost.

Exported Classes

There are no global classes defined by this module.

[Home] [ToC] [Prev] [Next]

_________.oo_Q_Q_oo.____________________________________________

Dianne Kyra Hackborn <hackbod@angryredplanet.com>
Last modified: Thu Oct 17 22:00:48 PDT 1996

This web page and all material contained herein is Copyright (c) 1997 Dianne Hackborn, unless otherwise noted. All rights reserved.