3.8 KiB
Homerun Model Specification
Homerun models make heavy use of Qt introspection and duck-typing. This document describes the mandatory and optional roles, properties and signals of a Homerun model.
Mandatory elements
Roles
string display
The item text.
string|QIcon decoration
The item icon, as a string or as a QIcon.
Properties
string name
- access: read-only
Returns a translated name for the model. This name is used as a title for the view associated with the model.
int count
- access: read-only
Returns current number of rows. Most often it will simply return rowCount(QModelIndex()).
Methods
bool trigger(int row, string actionId = "", QVariant actionArgument = QVariant())
Triggers the action identified by actionId on the item at row row.
actionId and actionArgument are defined in the actionList role.
Returns true if you want Homerun to close, false otherwise.
Note: When the user clicks on an item, actionId is an empty string.
To create items which can be favorited
Roles
string favoriteId
Unique Id used to favorite this item. Its value depends on the item type:
- item cannot be favorited: ""
- item is an application: "app:" + $desktopName. Examples: "app:inkscape.desktop" or "app:kde4-dolphin.desktop" for KDE applications.
- item is a place: "place:" + $url. Examples: "place:file:///home/jdoe/Documents" or "place:sftp://host.com/dir".
To create items with actions
Roles
bool hasActionList
Set to true if the item has additional actions, defined by the actionList role.
QVariantList actionList
A list of QVariantMap describing extra actions. Each map should contain the following elements:
- string type
- mandatory: no, default to "action"
- Can be one of "action", "title" or "separator"
- string text
- mandatory: yes
- The visible text shown in the item context menu
- QIcon icon
- mandatory: no
- The icon associated with the action
- string actionId
- mandatory: yes
- An id passed to trigger() to distinguish between actions
- variant actionArgument
- mandatory: no
- An optional argument, passed to trigger() as well
- bool enabled
- mandatory: no
- If set to true or omitted, the item will be enabled. If set to false, it will be disabled
Functions from the Homerun::ActionList namespace simplify the creation of actions.
Important: This role is ignored if hasActionList is not defined or returns false.
To create browsable models
Properties
Homerun::PathModel pathModel
- access: read-only
This property must return a Homerun::PathModel instance representing the position inside the model.
Signals
openSourceRequested(QString sourceId, const QVariantMap &arguments)
Emitted by a model when it wants another source to be opened by the view. This is used for example to open a browsable model in a subdir.
Note: If you want to be able to access your model this way, you need to implement Homerun::AbstractSource::createModelFromArguments().
To give running feedback
Properties
bool running
- access: read-only
Set to true to indicate the model is busy filling itself. Homerun will show a busy indicator as long as this property is true.
To provide custom searching/filtering
Properties
string query
- access: read-write
A model can implement this property to implement searching/filtering itself. If it is not defined, Homerun will apply a generic filter to the item names when the user type a search criteria.
To let the user reorder items
Properties
bool canMoveRow
- access: read-only
Implement this property and make it return true.
Methods
void moveRow(int from, int to)
This method should move row from to row to in the model and take care of
any necessary serialization.