Methods

OpenOffice.org Developer's Guide

OpenOffice.org API-Design-Guidelines

< Previous Section

Next Section >

• General Design Rules
• Definition of API Elements

• Attributes
• Methods
• Interfaces
• Properties
• Events
• Services
• Exceptions
• Enums
• Typedefs
• Structs
• Parameter

• Special Cases
• Abbreviations
• Source Files and Types

< Previous Page

Next Page >

Methods are functions defined within an interface. Technically, an interface only consists of methods. There is a syntax for attributes, but these map to methods.

Naming

Method identifiers begin with a verb in lowercase, for example, close, and continue with initial caps, that is, the first letter of each word is capitalized with no underscores. For example, getFormat().

Method names consisting of a verb without any additional terms can only be used if they refer to the object as a whole, and do not operate on parts of the object specified with arguments of this method. This makes names semantically more precise, and we avoid the risk of two method names of two different interfaces at the same object folding into each other causing problems with scripting languages.

Special attention should be given to uniformity within semantically related interfaces. This means, if a method is named destroyRecord(), an insert method should be called insertRecord().

If a method refers to a part of the object and an argument specifies this part, the type or role of the part is appended to the verbal part of the method,for example, removeFrame( [in] XFrame xFrame ). If the name of the part or its position is specified as an argument, ByName or ByIndex is additionally appended, for example, removeFrameByName( [in] string aName ) or removeFrameByIndex( [in] long nIndex ).

The following method prefixes have special meanings:

get

To return non-boolean values or interfaces of other objects that have a lasting relationship with the object the associated interface belongs to, similar to being an attribute. This prefix is generated automatically for readable attributes. Multiple calls to the same method at the same object with the same arguments, without modifying the object in between, returns the same value or interface.

set

To set values or interfaces of other objects that get into a lasting relationship with the object the associated interface belongs to, similar to becoming attribute values. This prefix is generated automatically for writable attributes.

query

This prefix is used to return values, including interfaces that have to be calculated at runtime or do not have the character of being a structural part of the object which belongs to the associated interface. Multiple calls, even without modifying the object in between, do not necessarily return the same value and interface; but this can be specified in the specific methods.

is/has

Usage is similar to get, and is used for boolean values.

create

This prefix is used for factory methods. Factory methods create and return new instances of objects. In many cases, the same or a related interface has an insert or add method.

insert

This prefix inserts new sub objects into an object when the insertion position is specified.

add

This prefix inserts new sub objects into an object when the insertion position is not specified by any argument of the method.

append

This prefix inserts new sub objects into an object when the new sub object gets appended at the end of the collection of sub objects.

remove

This prefix removes sub objects from a container. Use destroy if the removal implies the explicit destruction of the sub object. If the sub object is given as an argument, use it's type or role additionally, for example, removeFrame() if the argument is a Frame. If the position index or name of the sub object to remove is given, use a name similar to removeFrameByName(). For generic interfaces, use removeByName() without the type name or role, which are unknown in that case.

destroy

This prefix removes sub objects from a container and explicitly destroys them in this process. Use destroy as a verbal prefix. For more details, see the description of remove.

clear

This prefix clears contents of an object as a whole, the verb itself, or certain parts of the object, such as add a specifying name giving something like clearDelegates().

dispose

This prefix initiates a broadcast message to related objects to clear references to the object. Normally, this verb is only used in XComponent.

approve

This prefix is used for the approval notification in listener interfaces of prohibited events.

Usage

Non-structural attributes are represented by the property concept, and not by get and set methods, or attributes of interfaces.

Consider possible implementations if there are several possible interfaces where you could put a method. For example, a file cannot destroy itself, but the container directory could.

Do not use const as an attribute for methods, because future versions of UNOIDL will not support this feature.

Content on this page is licensed under the Public Documentation License (PDL).