diff options
Diffstat (limited to 'doc/en/plugins.txt')
| -rw-r--r-- | doc/en/plugins.txt | 76 |
1 files changed, 50 insertions, 26 deletions
diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 079e258b..6e829d5f 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -19,13 +19,15 @@ Methods Overridden methods ~~~~~~~~~~~~~~~~~~ -The *Plugin* class has several method that you can override for your own convenience +The *Plugin* class has several method that you can override for your own + convenience [[init]] *init*:: +self+ + This method is called when the plugin is loaded, this is where you call the other methods, for example <<add-command,add_command>>, and initialize -everything to make your plugin actually do something. <<example-1,ex 1>>, <<example-2,ex 2>> +everything to make your plugin actually do something. <<example-1,ex 1>>, + <<example-2,ex 2>> *cleanup*:: +self+ + Called when the plugin is unloaded (or when poezio is exited). Clean everything @@ -43,23 +45,23 @@ This method adds a global command to poezio. For example you can add a /foo command that the user could call when the plugin is loaded, by calling this method with _foo_ as its _name_ argument. <<example-1,ex 1>> -* _name_: (string) the name of the command (for example, if it is 'plugintest', it can -add a /plugintest command) +* _name_: (string) the name of the command (for example, if it is 'plugintest', + it can add a /plugintest command) * _handler_: (function) the function to be called when the command is executed. the handler takes *args* as a parameter, which is a string of what is entered after the command. Split *args* (with _common.shell_split_) to use that as command arguments. -* _help_: (string) the help message available for that command through the _/help_ -command. -* _completion_: (function) the completion for the args of that command. It takes -an input object as its only argument. This function should call the -_auto_completion()_ method on the input object, passing a list of possible strings -for the completion and returning the value of that call directly. -Everything else is handled by that _auto_completion()_ method (checking what strings -match, how to cycle between matches, etc). If you don’t want any special completion -for that command, just pass None (the default value). - -*add_event_handler**: +self+, +event_name+, +handler+ + +* _help_: (string) the help message available for that command through the + _/help_ command. +* _completion_: (function) the completion for the args of that command. It + takes an input object as its only argument. This function should call the +_auto_completion()_ method on the input object, passing a list of possible + strings for the completion and returning the value of that call directly. +Everything else is handled by that _auto_completion()_ method (checking what + strings match, how to cycle between matches, etc). If you don’t want any + special completion for that command, just pass None (the default value). + +*add_event_handler**: +self+, +event_name+, +handler+ +position+ This methods adds a callback that will be called whenever the given event occurs. <<example-2,ex 2>> @@ -67,7 +69,12 @@ occurs. <<example-2,ex 2>> This can be a sleekxmpp event, or a poezio event. See the list of <<events-list,all available events>>. * _handler_: The method that will be called whenever the event occurs. -It must accept the arguments specified for that event in the <<events-list,events list>>. +It must accept the arguments specified for that event in the + <<events-list,events list>>. +* _position_: Optional, this argument will specify the position of the handler + in the handler list for this event. It is 0 by default, and will only be used + with the internal poezio events described below. + Attributes ---------- @@ -77,14 +84,20 @@ Config By default, each plugin has a PluginConfig object accessible with *self.config*. *PluginConfig.read*:: +self+ + -Reads the config file from $XDG_CONFIG_HOME/poezio/plugins/plugin_name.cfg, it is called upon initialization, so you should not need it. +Reads the config file from $XDG_CONFIG_HOME/poezio/plugins/plugin_name.cfg, it + is called upon initialization, so you should not need it. *PluginConfig.write*:: +self+ + Writes the config to the same file mentioned previously. Core ~~~~ -Each plugin has a reference to the Core object accessible with *self.core*, that allows you to do about anything with poezio. Remember to use it only when you need it, and to use the functions described in this documentation only, even if much more is available. If your plugin needs to do something not available with these methods, please do a feature request instead of doing some dirty hacks with some other methods. +Each plugin has a reference to the Core object accessible with *self.core*, + that allows you to do about anything with poezio. Remember to use it only when + you need it, and to use the functions described in this documentation only, + even if much more is available. If your plugin needs to do something not + available with these methods, please do a feature request instead of doing + some dirty hacks with some other methods. Core methods ^^^^^^^^^^^^ @@ -98,49 +111,60 @@ Events list SleekXMPP events ~~~~~~~~~~~~~~~~ -For the sleekxmpp events, please refer to the https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. +For the sleekxmpp events, please refer to the + https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. Poezio events ~~~~~~~~~~~~~ *muc_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a MUC (through the /say command or by direct input). The parameters given to the handlers anre: +The handlers for this event are called whenever you say something in a MUC + (through the /say command or by direct input). The parameters given to the + handlers are: * _message_: Message to be sent * _tab_: Tab in which the message will be sent *private_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a private conversaton in a MUC (through the /say command or by direct input). The parameters given to the handlers are: +The handlers for this event are called whenever you say something in a private + conversaton in a MUC (through the /say command or by direct input). The + parameters given to the handlers are: * _message_: Message to be sent * _tab_: Tab in which the message will be sent *conversation_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in direct conversation (through the /say command or by direct input). The parameters given to the handler are: +The handlers for this event are called whenever you say something in direct + conversation (through the /say command or by direct input). The parameters + given to the handler are: * _message_: Message to be sent * _tab_: Tab in which the message will be sent *muc_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a MUC. The parameters given to the handler are: +The handlers for this event are called whenever you receive a message in a MUC. + The parameters given to the handler are: * _message_: Message received * _tab_: Tab in which the message was received *private_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a private conversation in a MUC. The parameters given to the handler are: +The handlers for this event are called whenever you receive a message in a + private conversation in a MUC. The parameters given to the handler are: * _message_: Message received * _tab_: Tab in which the message was received *conversation_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a direct conversation. The parameters given to the handler are: +The handlers for this event are called whenever you receive a message in a + direct conversation. The parameters given to the handler are: * _message_: Message received * _tab_: Tab in which the message was received -CAUTION: Plugins are in an experimental state and this API might change slightly in a near future. You have to be aware of that while making a plugin. +CAUTION: Plugins are in an experimental state and this API might change + slightly in a near future. You have to be aware of that while making a plugin. Examples -------- |