PBS Controller API

From PBS

Jump to: navigation, search

This page lists the API that plugins can use to access the data via the Controller interface.

Depending on the needs of each plugin, the API is split in 4 different sections:

  • Readers: The API used to access the data in Read-only. Using methods from this API, you will never modify any data.
  • Actions: The API used to modify the data. Those methods are used to alter data.
  • GUIHelpers: The API used to drive some GUI components. Very handy to write integration plugins.
  • Notifiers: The API used to notify views that an event has occurred. Normally a plugin developer should not use them directly, as Actions methods already use them. Therefore they won't be declined in this section. If you want your integration plugin to be notified when such a notification event occurs, see PBS Events API documentation.

In order to better understand interfaces of the methods in the API, you should have a look at some model objects description: the Shortcut object and Tag object. They are the 2 main objects you will deal with in the API.

Contents

[edit] Readers

[edit] Current data

Methods giving access to the data currently loaded in PBS.

[edit] CurrentOpenedFileName

# The current opened file name
#   String
def CurrentOpenedFileName

[edit] CurrentOpenedFileModified

# Is the current opened file modified ?
#   Boolean
def CurrentOpenedFileModified

[edit] RootTag

# The Root tag
#   Tag
def RootTag

[edit] ShortcutsList

# The list of Shortcuts
#   list< Shortcut >
def ShortcutsList

[edit] getTagIcon

# Get the icon associated to a Tag.
# Even if it was set to nil, the default icon will be returned.
# This method ensures a valid Wx::Bitmap object will be returned.
#
# Parameters:
# * *iTag* (_Tag_): The Tag
# Return:
# * Wx::Bitmap: The icon
def getTagIcon(iTag)

[edit] getShortcutIcon

# Get the icon associated to a Shortcut.
# Even if it was set to nil, the default icon will be returned.
# This method ensures a valid Wx::Bitmap object will be returned.
#
# Parameters:
# * *iShortcut* (_Shortcut_): The Shortcut
# Return:
# * Wx::Bitmap: The icon
def getShortcutIcon(iShortcut)

[edit] Plugins

Methods listing loaded plugins.

[edit] TypesPlugins

# Types plugins
#   map< String, map< Symbol, Object > >
def TypesPlugins

[edit] ImportPlugins

# Import plugins
#   map< String, map< Symbol, Object > >
def ImportPlugins

[edit] ExportPlugins

# Export plugins
#   map< String, map< Symbol, Object > >
def ExportPlugins

[edit] IntegrationPlugins

# Integration plugins
#   map< String, map< Symbol, Object > >
def IntegrationPlugins

[edit] Local clipboard

Methods giving information on what has been copied/cut from this PBS execution.

[edit] CopiedMode

# The current type of copy (Wx::ID_COPY or Wx::ID_CUT)
#   Integer
def CopiedMode

[edit] CopiedID

# The current ID of what we have copied
#   Integer
def CopiedID

[edit] CopiedSelection

# The current copied selection
#   MultipleSelection
def CopiedSelection

[edit] Local drag

Methods giving information on what is being dragged from this PBS execution.

[edit] DragMode

# The current type of drag (Wx::DRAG_COPY or Wx::DRAG_MOVE)
#   Integer
def DragMode

[edit] DragSelection

# The current dragged selection
#   MultipleSelection
def DragSelection

[edit] Clipboard content

Methods giving information about the clipboard's content

[edit] Clipboard_CopyMode

# Mode of Copy of the clipboard's content
#   Integer
def Clipboard_CopyMode

[edit] Clipboard_CopyID

# ID of the clipboard's content
#   Integer
def Clipboard_CopyID

[edit] Clipboard_SerializedSelection

# Serialized selection in the clipboard
#   MultipleSelection::Serialized
def Clipboard_SerializedSelection

[edit] Other methods

[edit] Options

# Options
#   map< Symbol, Object >
def Options

[edit] UndoStack

# The Undo stack
#   list< Controller::UndoableOperation >
def UndoStack

[edit] RedoStack

# The Redo stack
#   list< Controller::UndoableOperation >
def RedoStack

[edit] Actions

[edit] Tags modification

[edit] createTag

# Create a Tag if it does not exist already, and return it.
# This method is protected for Undo/Redo management.
#
# Parameters:
# * *iParentTag* (_Tag_): The parent Tag
# * *iTagName* (_String_): The new Tag name
# * *iIcon* (Wx::Bitmap): The icon (can be nil)
# Return:
# * _Tag_: The created Tag.
def createTag(iParentTag, iTagName, iIcon)

[edit] deleteTag

# Delete a Tag.
# It also deletes all its sub-Tags.
# It is assumed that no Shortcut references it any longer before calling this function, as well as any of its sub-Tags.
#
# Parameters:
# * *iTag* (_Tag_): The Tag to delete
def deleteTag(iTag)

[edit] updateTag

# Modify the Tag based on new data.
# Only this method should be used by commands to update a Tag's info.
#
# Parameters:
# * *ioTag* (_Tag_): The Tag to modify
# * *iNewName* (_String_): The new name
# * *iNewIcon* (Wx::Bitmap): The new icon (can be nil)
# * *iNewChildren* (list<Tag>): The new list of sub-Tags
# Return:
# * _Boolean_: Did the data effectively changed ? (It will also be true if the update resulted in a delete of the Tag)
def updateTag(ioTag, iNewName, iNewIcon, iNewChildren)

[edit] Shortcuts modification

[edit] createShortcut

# Create a Shortcut if it does not exit, or merge Tags if already existing.
#
# Parameters:
# * *iTypeName* (_String_): The type name
# * *iContent* (_Object_): The content
# * *iMetadata* (map<String,Object>): The metadata
# * *iTags* (map<Tag,nil>): The set of Tags
# Return:
# * _Shortcut_: The newly created Shortcut
def createShortcut(iTypeName, iContent, iMetadata, iTags)

[edit] deleteShortcut

# Delete a given Shortcut
#
# Parameters:
# * *iShortcut* (_Shortcut_): The Shortcut to delete
def deleteShortcut(iShortcut)

[edit] updateShortcut

# Modify the Shortcut based on new data.
# Only this method should be used by commands to update a Shortcut's info.
#
# Parameters:
# * *ioSC* (_Shortcut_): The Shortcut to modify
# * *iNewContent* (_Object_): The new Content
# * *iNewMetadata* (map<String,Object>): The new Metadata
# * *iNewTags* (map<Tag,nil>): The new Tags
# Return:
# * _Boolean_: Did the data effectively changed ? (It will also be true if the update resulted in a delete of the Shortcut)
def updateShortcut(ioSC, iNewContent, iNewMetadata, iNewTags)

[edit] Current opened file

[edit] changeCurrentFileName

# Change the current file name opened.
# This also resets the FileModified flag to false.
#
# Parameters:
# * *iNewFileName* (_String_): New file name
def changeCurrentFileName(iNewFileName)

[edit] setCurrentFileModified

# Change the current file modified status.
def setCurrentFileModified

[edit] checkSavedWorkAndScratch

# Method that check current work is saved, asks the user if not, and scratches the whole data.
# In merge context, it does nothing.
#
# Parameters:
# * *iParentWindow* (Wx::Window): The parent window
# Return:
# * _Boolean_: Has current work been saved (true also if user decides to continue without saving deliberately) ?
def checkSavedWorkAndScratch(iParentWindow)

[edit] checkSavedWork

# Method that check current work is saved, asks the user if not.
#
# Parameters:
# * *iParentWindow* (Wx::Window): The parent window
# Return:
# * _Boolean_: Has current work been saved (true also if user decides to continue without saving deliberately) ?
def checkSavedWork(iParentWindow)

[edit] Other methods

[edit] undoableOperation

# Perform an operation, protected with Undo/Redo methods
#
# Parameters:
# * *iOperationTitle* (_String_): Title of the operation to perform to display as undo
def undoableOperation(iOperationTitle)
# Execute a given command
#
# Parameters:
# * *iCommandID* (_Integer_): The command ID
# * *iParams* (map<Symbol,Object>): The parameters to give the command (nil if no parameters) [optional = nil]
def executeCommand(iCommandID, iParams = nil)

[edit] GUIHelpers

Methods useful for GUI developers to integrate PBS components in their plugins.

[edit] Adding PBS commands to a GUI

[edit] setAcceleratorTableForFrame

# Set the accelerator table for a given frame
#
# Parameters:
# * *oFrame* (Wx::Frame): The frame for which we set the accelerator table
def setAcceleratorTableForFrame(oFrame)

[edit] addMenuCommand

# Add a command in a menu.
# this method does not return the created menu item, as it will be deleted/recreated each time its appearance will be updated (limitations certainly due to bugs).
# To access to this menu later, always use the Wx::Menu object with the Command ID.
#
# Parameters:
# * *iEvtWindow* (Wx::EvtHandler): The event handler that will receive the command
# * *ioMenu* (Wx::Menu): The menu in which we add the command
# * *iCommandID* (_Integer_): ID of the command to add
# * *iParams* (map<Symbol,Object>): Additional properties, specific to this command item [optional = {}]
# * *&iFetchParametersCode* (_CodeBlock_): Code that will use a command validator to fetch parameters, or nil if none needed
def addMenuCommand(iEvtWindow, ioMenu, iCommandID, iParams = {}, &iFetchParametersCode)

[edit] addToolbarCommand

# Add a command in a toolbar
#
# Parameters:
# * *iToolbar* (Wx::Toolbar): The toolbar in which we add the command
# * *iCommandID* (_Integer_): ID of the command to add
# * *iParams* (map<Symbol,Object>): Additional properties, specific to this command item [optional = {}]
# Return:
# * Wx::ToolbarTool: The created toolbar button, or nil if none.
def addToolbarCommand(iToolbar, iCommandID, iParams = {})

[edit] Modify GUI elements dynamically

[edit] setMenuItemGUIEnabled

# Update the GUI Enabled property of a menu item.
# This property can put a veto to the enabling of a given command for this specific GUI (for example command Paste is enabled by the controller because there is something in the clipboard, but a particular GUI does not want it to be enabled because the user has not yet selected a place to Paste).
#
# Parameters:
# * *iMenu* (Wx::Menu): Menu to which the menu item belongs.
# * *iCommandID* (_Integer_): The command ID of the menu item
# * *iGUIEnabled* (_Boolean_): Do we accept enabling the command ?
def setMenuItemGUIEnabled(iMenu, iCommandID, iGUIEnabled)

[edit] setMenuItemGUITitle

# Update the GUI Title property of a menu item.
# If set, this property will override the title given by the controller.
#
# Parameters:
# * *iMenu* (Wx::Menu): Menu to which the menu item belongs.
# * *iCommandID* (_Integer_): The command ID of the menu item
# * *iGUITitle* (_String_): The title
def setMenuItemGUITitle(iMenu, iCommandID, iGUITitle)

[edit] setToolbarButtonGUIEnabled

# Update the GUI Enabled property of a toolbar button
# This property can put a veto to the enabling of a given command for this specific GUI (for example command Paste is enabled by the controller because there is something in the clipboard, but a particular GUI does not want it to be enabled because the user has not yet selected a place to Paste).
#
# Parameters:
# * *iToolbarButton* (Wx::ToolbarTool): The toolbar button
# * *iCommandID* (_Integer_): ID of the command to add
# * *iGUIEnabled* (_Boolean_): Do we accept enabling the command ?
def setToolbarButtonGUIEnabled(iToolbarButton, iCommandID, iGUIEnabled)

[edit] setToolbarButtonGUITitle

# Update the GUI Title property of a toolbar button
# If set, this property will override the title given by the controller.
#
# Parameters:
# * *iToolbarButton* (Wx::ToolbarTool): The toolbar button
# * *iCommandID* (_Integer_): ID of the command to add
# * *iGUITitle* (_String_): The title
def setToolbarButtonGUITitle(iToolbarButton, iCommandID, iGUITitle)
Personal tools