Package muntjac :: Package ui :: Module component :: Class IComponent
[hide private]
[frames] | no frames]

Class IComponent

source code

                        object --+        
                                 |        
               util.IEventListener --+    
                                     |    
         terminal.paintable.IPaintable --+
                                         |
                            object --+   |
                                     |   |
terminal.variable_owner.IVariableOwner --+
                                         |
                            object --+   |
                                     |   |
           terminal.sizeable.ISizeable --+
                                         |
                                        IComponent
Known Subclasses:

IComponent is the top-level interface that is and must be implemented by all Muntjac components. IComponent is paired with AbstractComponent, which provides a default implementation for all the methods defined in this interface.

Components are laid out in the user interface hierarchically. The layout is managed by layout components, or more generally by components that implement the ComponentContainer interface. Such a container is the parent of the contained components.

The getParent method allows retrieving the parent component of a component. While there is a setParent, you rarely need it as you normally add components with the addComponent() method of the layout or other ComponentContainer, which automatically sets the parent.

A component becomes attached to an application (and the attach is called) when it or one of its parents is attached to the main window of the application through its containment hierarchy.


Authors:
Vaadin Ltd., Richard Lincoln

Version: 1.1.2

Instance Methods [hide private]
 
getStyleName(self)
Gets all user-defined CSS style names of a component.
source code
 
setStyleName(self, style)
Sets one or more user-defined style names of the component, replacing any previous user-defined styles.
source code
 
addStyleName(self, style)
Adds a style name to component.
source code
 
removeStyleName(self, style)
Removes one or more style names from component.
source code
 
isEnabled(self)
Tests whether the component is enabled or not.
source code
 
setEnabled(self, enabled)
Enables or disables the component.
source code
 
isVisible(self)
Tests the visibility property of the component.
source code
 
setVisible(self, visible)
Sets the visibility of the component.
source code
 
getParent(self)
Gets the parent component of the component.
source code
 
setParent(self, parent)
Sets the parent component of the component.
source code
 
isReadOnly(self)
Tests whether the component is in the read-only mode.
source code
 
setReadOnly(self, readOnly)
Sets the read-only mode of the component to the specified mode.
source code
 
getCaption(self)
Gets the caption of the component.
source code
 
setCaption(self, caption)
Sets the caption of the component.
source code
 
getIcon(self)
Gets the icon resource of the component.
source code
 
setIcon(self, icon)
Sets the icon of the component.
source code
 
getWindow(self)
Gets the parent window of the component.
source code
 
getApplication(self)
Gets the application object to which the component is attached.
source code
 
attach(self)
Notifies the component that it is connected to an application.
source code
 
detach(self)
Notifies the component that it is detached from the application.
source code
 
getLocale(self)
Gets the locale of the component.
source code
 
childRequestedRepaint(self, alreadyNotified)
The child components of the component must call this method when they need repainting.
source code
 
addListener(self, listener, iface=None)
Registers a new (generic) component event listener for the component:
source code
 
addCallback(self, callback, eventType=None, *args) source code
 
removeListener(self, listener, iface=None)
Removes a previously registered component event listener from this component.
source code
 
removeCallback(self, callback, eventType=None) source code

Inherited from terminal.paintable.IPaintable: getDebugId, paint, requestRepaint, requestRepaintRequests, setDebugId

Inherited from terminal.variable_owner.IVariableOwner: changeVariables, isImmediate

Inherited from terminal.sizeable.ISizeable: getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeightUnits, setSizeFull, setSizeUndefined, setWidth, setWidthUnits

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]

Inherited from terminal.sizeable.ISizeable: SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS, UNIT_SYMBOLS

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

getStyleName(self)

source code 

Gets all user-defined CSS style names of a component. If the component has multiple style names defined, the return string is a space-separated list of style names. Built-in style names defined in Muntjac or GWT are not returned.

The style names are returned only in the basic form in which they were added; each user-defined style name shows as two CSS style class names in the rendered HTML: one as it was given and one prefixed with the component-specific style name. Only the former is returned.

Returns:
the style name or a space-separated list of user-defined style names of the component

setStyleName(self, style)

source code 

Sets one or more user-defined style names of the component, replacing any previous user-defined styles. Multiple styles can be specified as a space-separated list of style names. The style names must be valid CSS class names and should not conflict with any built-in style names in Muntjac or GWT:

 label = new Label("This text has a lot of style")
 label.setStyleName("myonestyle myotherstyle")

Each style name will occur in two versions: one as specified and one that is prefixed with the style name of the component. For example, if you have a Button component and give it "mystyle" style, the component will have both "mystyle" and "v-button-mystyle" styles. You could then style the component either with:

 .myonestyle {background: blue;}

or:

 .v-button-myonestyle {background: blue;}

It is normally a good practice to use addStyleName rather than this setter, as different software abstraction layers can then add their own styles without accidentally removing those defined in other layers.

This method will trigger a RepaintRequestEvent.

Parameters:
  • style - the new style or styles of the component as a space-separated list

addStyleName(self, style)

source code 

Adds a style name to component. The style name will be rendered as a HTML class name, which can be used in a CSS definition:

 label = new Label("This text has style")
 label.addStyleName("mystyle")

Each style name will occur in two versions: one as specified and one that is prefixed wil the style name of the component. For example, if you have a Button component and give it "mystyle" style, the component will have both "mystyle" and "v-button-mystyle" styles. You could then style the component either with:

 .mystyle {font-style: italic;}

or:

 .v-button-mystyle {font-style: italic;}

This method will trigger a RepaintRequestEvent.

Parameters:
  • style - the new style to be added to the component

removeStyleName(self, style)

source code 

Removes one or more style names from component. Multiple styles can be specified as a space-separated list of style names.

The parameter must be a valid CSS style name. Only user-defined style names added with addStyleName or setStyleName can be removed; built-in style names defined in Muntjac or GWT can not be removed.

This method will trigger a RepaintRequestEvent.

Parameters:
  • style - the style name or style names to be removed

isEnabled(self)

source code 

Tests whether the component is enabled or not. A user can not interact with disabled components. Disabled components are rendered in a style that indicates the status, usually in gray color. Children of a disabled component are also disabled. Components are enabled by default.

As a security feature, all variable change events for disabled components are blocked on the server-side.

Returns:
True if the component and its parent are enabled, False otherwise.
Overrides: terminal.variable_owner.IVariableOwner.isEnabled

setEnabled(self, enabled)

source code 

Enables or disables the component. The user can not interact disabled components, which are shown with a style that indicates the status, usually shaded in light gray color. Components are enabled by default. Children of a disabled component are automatically disabled; if a child component is explicitly set as disabled, changes in the disabled status of its parents do not change its status:

 enabled = new Button("Enabled")
 enabled.setEnabled(True)  # the default
 layout.addComponent(enabled)

 disabled = Button("Disabled")
 disabled.setEnabled(False)
 layout.addComponent(disabled)

This method will trigger a RepaintRequestEvent for the component and, if it is a ComponentContainer, for all its children recursively.

Parameters:
  • enabled - a boolean value specifying if the component should be enabled or not

isVisible(self)

source code 

Tests the visibility property of the component.

Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change, but the entire HTML element will be empty. Making a component invisible through this property can alter the positioning of other components.

A component is visible only if all its parents are also visible. Notice that if a child component is explicitly set as invisible, changes in the visibility status of its parents do not change its status.

This method does not check whether the component is attached (see attach). The component and all its parents may be considered "visible", but not necessarily attached to application. To test if component will actually be drawn, check both its visibility and that getApplication does not return None.

Returns:
True if the component is visible in the user interface, False if not
See Also:
setVisible, attach

setVisible(self, visible)

source code 

Sets the visibility of the component.

Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change, but the entire HTML element will be empty:

 readonly = TextField("Read-Only")
 readonly.setValue("You can't see this!")
 readonly.setVisible(False)
 layout.addComponent(readonly)

A component is visible only if all of its parents are also visible. If a component is explicitly set to be invisible, changes in the visibility of its parents will not change the visibility of the component.

Parameters:
  • visible - the boolean value specifying if the component should be visible after the call or not.

See Also: isVisible

getParent(self)

source code 

Gets the parent component of the component.

Components can be nested but a component can have only one parent. A component that contains other components, that is, can be a parent, should usually inherit the ComponentContainer interface.

Returns:
the parent component

See Also: setParent

setParent(self, parent)

source code 

Sets the parent component of the component.

This method automatically calls attach if the parent becomes attached to the application, regardless of whether it was attached previously. Conversely, if the parent is None and the component is attached to the application, detach is called for the component.

This method is rarely called directly. The ComponentContainer.addComponent method is normally used for adding components to a container and it will call this method implicitly.

It is not possible to change the parent without first setting the parent to None.

Parameters:
  • parent - the parent component
Raises:
  • ValueError - if a parent is given even though the component already has a parent

isReadOnly(self)

source code 

Tests whether the component is in the read-only mode. The user can not change the value of a read-only component. As only IField components normally have a value that can be input or changed by the user, this is mostly relevant only to field components, though not restricted to them.

Notice that the read-only mode only affects whether the user can change the value of the component; it is possible to, for example, scroll a read-only table.

The read-only status affects only the user; the value can still be changed programmatically, for example, with IProperty.setValue.

The method will return True if the component or any of its parents is in the read-only mode.

Returns:
True if the component or any of its parents is in read-only mode, False if not.

See Also: setReadOnly

setReadOnly(self, readOnly)

source code 

Sets the read-only mode of the component to the specified mode. The user can not change the value of a read-only component.

As only IField components normally have a value that can be input or changed by the user, this is mostly relevant only to field components, though not restricted to them.

Notice that the read-only mode only affects whether the user can change the value of the component; it is possible to, for example, scroll a read-only table.

The read-only status affects only the user; the value can still be changed programmatically, for example, with IProperty.setValue.

This method will trigger a RepaintRequestEvent.

Parameters:
  • readOnly - a boolean value specifying whether the component is put read-only mode or not

getCaption(self)

source code 

Gets the caption of the component.

See setCaption for a detailed description of the caption.

Returns:
the caption of the component or null if the caption is not set.

See Also: setCaption

setCaption(self, caption)

source code 

Sets the caption of the component.

A caption is an explanatory textual label accompanying a user interface component, usually shown above, left of, or inside the component. Icon (see setIcon is closely related to caption and is usually displayed horizontally before or after it, depending on the component and the containing layout.

The caption can usually also be given as the first parameter to a constructor, though some components do not support it:

 area = new RichTextArea()
 area.setCaption("You can edit stuff here")
 area.setValue("<h1>Helpful Heading</h1>"
       + "<p>All this is for you to edit.</p>")

The contents of a caption are automatically quoted, so no raw XHTML can be rendered in a caption. The validity of the used character encoding, usually UTF-8, is not checked.

The caption of a component is, by default, managed and displayed by the layout component or component container in which the component is placed. For example, the VerticalLayout component shows the captions left-aligned above the contained components, while the FormLayout component shows the captions on the left side of the vertically laid components, with the captions and their associated components left-aligned in their own columns. The CustomComponent does not manage the caption of its composition root, so if the root component has a caption, it will not be rendered. Some components, such as Button and Panel, manage the caption themselves and display it inside the component.

This method will trigger a RepaintRequestEvent. A reimplementation should call the superclass implementation.

Parameters:
  • caption - the new caption for the component. If the caption is None, no caption is shown and it does not normally take any space

getIcon(self)

source code 

Gets the icon resource of the component.

See setIcon for a detailed description of the icon.

Returns:
the icon resource of the component or None if the component has no icon

See Also: setIcon

setIcon(self, icon)

source code 

Sets the icon of the component.

An icon is an explanatory graphical label accompanying a user interface component, usually shown above, left of, or inside the component. Icon is closely related to caption (see setCaption) and is usually displayed horizontally before or after it, depending on the component and the containing layout.

The image is loaded by the browser from a resource, typically a ThemeResource:

 # IComponent with an icon from a custom theme
 name = TextField("Name")
 name.setIcon(ThemeResource("icons/user.png"))
 layout.addComponent(name)

 # IComponent with an icon from another theme ('runo')
 ok = Button("OK")
 ok.setIcon(ThemeResource("../runo/icons/16/ok.png"))
 layout.addComponent(ok)

The icon of a component is, by default, managed and displayed by the layout component or component container in which the component is placed. For example, the VerticalLayout component shows the icons left-aligned above the contained components, while the FormLayout component shows the icons on the left side of the vertically laid components, with the icons and their associated components left-aligned in their own columns. The CustomComponent does not manage the icon of its composition root, so if the root component has an icon, it will not be rendered.

An icon will be rendered inside an HTML element that has the v-icon CSS style class. The containing layout may enclose an icon and a caption inside elements related to the caption, such as v-caption .

This method will trigger a RepaintRequestEvent.

Parameters:
  • icon - the icon of the component. If null, no icon is shown and it does not normally take any space.
See Also:
getIcon, setCaption

getWindow(self)

source code 

Gets the parent window of the component.

If the component is not attached to a window through a component containment hierarchy, None is returned.

The window can be either an application-level window or a sub-window. If the component is itself a window, it returns a reference to itself, not to its containing window (of a sub-window).

Returns:
the parent window of the component or None if it is not attached to a window or is itself a window

getApplication(self)

source code 

Gets the application object to which the component is attached.

The method will return None if the component is not currently attached to an application. This is often a problem in constructors of regular components and in the initializers of custom composite components. A standard workaround is to move the problematic initialization to attach, as described in the documentation of the method.

Returns:
the parent application of the component or None.

See Also: attach

attach(self)

source code 

Notifies the component that it is connected to an application.

The caller of this method is setParent if the parent is itself already attached to the application. If not, the parent will call the attach for all its children when it is attached to the application. This method is always called before the component is painted for the first time.

Reimplementing the attach() method is useful for tasks that need to get a reference to the parent, window, or application object with the getParent, getWindow, and getApplication methods. A component does not yet know these objects in the constructor, so in such case, the methods will return None. For example, the following is invalid:

 class AttachExample(CustomComponent):
     def __init__(self):
         # ERROR: We can't access the application object yet.
         r = ClassResource("smiley.jpg", getApplication())
         image = Embedded("Image:", r)
         setCompositionRoot(image)

Adding a component to an application triggers calling the attach method for the component. Correspondingly, removing a component from a container triggers calling the detach method. If the parent of an added component is already connected to the application, the attach() is called immediately from setParent:

 class AttachExample(CustomComponent):
     def __init__(self):
         pass

     def attach(self):
         super(AttachExample, self).attach()  # must call

         # Now we know who ultimately owns us.
         r = ClassResource("smiley.jpg", self.getApplication())
         image = Embedded("Image", r)
         self.setCompositionRoot(image)

The attachment logic is implemented in AbstractComponent.

See Also: getApplication

detach(self)

source code 

Notifies the component that it is detached from the application.

The getApplication and getWindow methods might return None after this method is called.

The caller of this method is setParent if the parent is in the application. When the parent is detached from the application it is its response to call detach for all the children and to detach itself from the terminal.

getLocale(self)

source code 

Gets the locale of the component.

If a component does not have a locale set, the locale of its parent is returned, and so on. Eventually, if no parent has locale set, the locale of the application is returned. If the application does not have a locale set, it is determined by getDefaultLocale().

As the component must be attached before its locale can be acquired, using this method in the internationalization of component captions, etc. is generally not feasible. For such use case, we recommend using an otherwise acquired reference to the application locale.

Returns:
Locale of this component or null if the component and none of its parents has a locale set and the component is not yet attached to an application.

childRequestedRepaint(self, alreadyNotified)

source code 

The child components of the component must call this method when they need repainting. The call must be made even in the case in which the children sent the repaint request themselves.

A repaint request is ignored if the component is invisible.

This method is called automatically by AbstractComponent, which also provides a default implementation of it. As this is a somewhat internal feature, it is rarely necessary to reimplement this or call it explicitly.

Parameters:
  • alreadyNotified - the collection of repaint request listeners that have been already notified by the child. This component should not re-notify the listed listeners again. The container given as parameter must be modifiable as the component might modify it and pass it forward. A None parameter is interpreted as an empty collection.

addListener(self, listener, iface=None)

source code 

Registers a new (generic) component event listener for the component:

 class Listening(CustomComponent, IListener):

     # Stored for determining the source of an event
     ok = None

     status = None  # For displaying info about the event

     def __init__(self):
         layout = VerticalLayout()

         # Some miscellaneous component
         name = TextField("Say it all here")
         name.addListener(self)
         name.setImmediate(true)
         layout.addComponent(name)

         # Handle button clicks as generic events instead
         # of Button.ClickEvent events
         ok = new Button("OK")
         ok.addListener(self)
         layout.addComponent(ok)

         # For displaying information about an event
         status = new Label("")
         layout.addComponent(status)

         setCompositionRoot(layout)


     def componentEvent(event):
         # Act according to the source of the event
         if (event.getSource() == ok):
             getWindow().showNotification("Click!")

         status.setValue("Event from " +
                 event.getSource().__class__.__name__
                 + ": " + event.__class__.__name__)


 listening = Listening()
 layout.addComponent(listening)
Parameters:
  • listener - the new IListener to be registered.
Overrides: terminal.paintable.IPaintable.addListener

addCallback(self, callback, eventType=None, *args)

source code 
Overrides: terminal.paintable.IPaintable.addCallback

removeListener(self, listener, iface=None)

source code 

Removes a previously registered component event listener from this component.

Parameters:
  • listener - the listener to be removed.
Overrides: terminal.paintable.IPaintable.removeListener

See Also: addListener

removeCallback(self, callback, eventType=None)

source code 
Overrides: terminal.paintable.IPaintable.removeCallback