moparisthebest/hexchat
1
0
Fork 0
mirror of https://github.com/moparisthebest/hexchat synced 2024-11-29 20:52:16 -05:00
Code Issues Releases Wiki Activity

Fix Python docs

Browse Source
This commit is contained in:
Berke Viktor 2012-10-28 15:36:28 +01:00
parent 31ed205e6e
commit 9c89cd7817
1 changed files with 250 additions and 261 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

393
share/doc/python.md
View File

@ -4,49 +4,46 @@
Here are some of the features of the python plugin interface: Here are some of the features of the python plugin interface:
- Comprehensive, consistent and straightforward API * Comprehensive, consistent and straightforward API
- Load, unload, reload, and autoload support * Load, unload, reload, and autoload support
- Per plugin independent interpreter state * Per plugin independent interpreter state
- Python interactive console * Python interactive console
- Python interactive command execution * Python interactive command execution
- Full thread support * Full thread support
- Stdout and stderr redirected to xchat console * Stdout and stderr redirected to xchat console
- Dynamic list management * Dynamic list management
- Nice context treatment * Nice context treatment
- Plugin preferences * Plugin preferences
## Commands ## Commands
The following commands will be intercepted by the Python Plugin interface module, when it is loaded. The following commands will be intercepted by the Python Plugin interface module, when it is loaded.
--------------------------------------------------------------------------------------------------------------------------------------------- * **/py load <filename>:** Load module with given filename.
*Command* *Description* * **/py unload <filename|module name>:** Unload module with given filename, or module name.
---------------------------------- --------------------------------------------------------------------------------------------------------- * **/py reload <filename|module name>:** Reload module with given filename, or module name.
/py load <filename> Load module with given filename. * **/py list:** List Python modules loaded.
* **/py exec &lt;command>:** Execute given Python command interactively. For example:
/py unload <filename|module name> Unload module with given filename, or module name. <pre>
/py exec import xchat
/py exec print xchat.get_info('channel')
</pre>
/py reload <filename|module name> Reload module with given filename, or module name. * **/py console:** Open the Python interactive console in a query (>>python<<).
Every message sent will be intercepted by the Python plugin interface,
and interpreted interactively. Notice that the console and /py exec
commands live in the same interpreter state.
/py list List Python modules loaded. * **/py about:** Show some information about the Python plugin interface.
/py exec <command> Execute given Python command interactively. For example:
`/py exec import xchat`
`/py exec print xchat.get_info('channel')`
/py console Open the Python interactive console in a query (>>python<<).
Every message sent will be intercepted by the Python plugin interface, and interpreted interactively.
Notice that the console and /py exec commands live in the same interpreter state.
/py about Show some information about the Python plugin interface.
----------------------------------------------------------------------------------------------------------------------------------------------
## Autoloading modules ## Autoloading modules
If you want some module to be autoloaded together with the Python plugin If you want some module to be autoloaded together with the Python plugin
interface (which usually loads at startup time), just make sure it has a interface (which usually loads at startup time), just make sure it has a
`.py` extension and put it in your HexChat directory (~/.config/hexchat/addons, %APPDATA%\\HexChat\\addons). `.py` extension and put it in your HexChat directory (`~/.config/hexchat/addons`, `%APPDATA%\\HexChat\\addons`).
## Context theory ## Context theory
@ -65,38 +62,42 @@ channel, and you have asked xchat to tell you about this event, the
current context will be set to this channel before your module is current context will be set to this channel before your module is
called. called.
## Hello world ## Hello world
Here is the traditional *hello world* example. Here is the traditional _hello world_ example.
~~~~~~~~~~ {.python} <pre>
__module_name__ = "helloworld" __module_name__ = "helloworld"
__module_version__ = "1.0" __module_version__ = "1.0"
__module_description__ = "Python module example" __module_description__ = "Python module example"
print "Hello world!" print "Hello world!"
~~~~~~~~~~ </pre>
This module will print "Hello world!" in the xchat console, and sleep This module will print "Hello world!" in the HexChat console, and sleep
forever until it's unloaded. It's a simple module, but already forever until it's unloaded. It's a simple module, but already
introduces some concepts. Notice how the module information is set. This introduces some concepts. Notice how the module information is set. This
information is obligatory, and will be shown when listing the loaded information is obligatory, and will be shown when listing the loaded
xchat modules. xchat modules.
## xchat module ## xchat module
The xchat module is your passport to every xchat functionality offered The xchat module is your passport to every xchat functionality offered
by the Python plugin interface. Here's a simple example: by the Python plugin interface. Here's a simple example:
~~~~~~~~~~ {.python} <pre>
import xchat import xchat
xchat.prnt("Hi everyone!") xchat.prnt("Hi everyone!")
~~~~~~~~~~ </pre>
The following functions are available in the xchat module. The following functions are available in the xchat module.
### Generic functions ### Generic functions
#### xchat.prnt(string) #### xchat.prnt(string)
This function will print string in the current context. It's mainly This function will print string in the current context. It's mainly
@ -104,19 +105,20 @@ useful as a parameter to pass to some other function, since the usual
print statement will have the same results. You have a usage example print statement will have the same results. You have a usage example
above. above.
This function is badly This function is badly named because `"print"` is a reserved keyword of the Python language.
named because `"print"` is a reserved keyword of the Python language.
#### xchat.emit_print(event_name, *args)
#### xchat.emit\_print(event\_name, \*args)
This function will generate a *print event* with the given arguments. To This function will generate a *print event* with the given arguments. To
check which events are available, and the number and meaning of check which events are available, and the number and meaning of
arguments, have a look at the `Settings > Lists > Text Events` window. arguments, have a look at the `Settings > Lists > Text Events` window.
Here is one example: Here is one example:
~~~~~~~~~~ {.python} <pre>
xchat.emit_print("Channel Message", "John", "Hi there", "@") xchat.emit_print("Channel Message", "John", "Hi there", "@")
~~~~~~~~~~` </pre>
#### xchat.command(string) #### xchat.command(string)
@ -124,9 +126,10 @@ Execute the given command in the current context. This has the same
results as executing a command in the xchat window, but notice that the results as executing a command in the xchat window, but notice that the
`/` prefix is not used. Here is an example: `/` prefix is not used. Here is an example:
~~~~~~~~~~ {.python} <pre>
xchat.command("server irc.openprojects.net") xchat.command("server irc.openprojects.net")
~~~~~~~~~~ </pre>
#### xchat.nickcmp(s1, s2) #### xchat.nickcmp(s1, s2)
@ -136,176 +139,162 @@ integer less than, equal to, or greater than zero if `s1` is found,
respectively, to be less than, to match, or be greater than `s2`. For respectively, to be less than, to match, or be greater than `s2`. For
example: example:
~~~~~~~~~~ {.python} <pre>
if xchat.nickcmp(nick, "mynick") == 0: if xchat.nickcmp(nick, "mynick") == 0:
print "They are the same!" print "They are the same!"
~~~~~~~~~~ </pre>
### Information retreiving functions ### Information retreiving functions
#### xchat.get_info(type)
#### xchat.get\_info(type)
Retrieve the information specified by the `type` string in the current Retrieve the information specified by the `type` string in the current
context. At the moment of this writing, the following information types context. At the moment of this writing, the following information types
are available to be queried: are available to be queried:
----------------------------------------------------------------------------------------------- * **away:** Away reason or None if you are not away.
*Type* *Description* * **channels** Channel of the current context.
-------- ----------------------------------------------------------------------------------- * **hostname:** Real hostname of the server you connected to.
away Away reason or None if you are not away. * **network:** Current network name or None.
* **nick:** Your current nick name.
channels Channel of the current context. * **server:** Current server name (what the server claims to be) or None if you are not connected.
* **topic:** Current channel topic.
hostname Real hostname of the server you connected to. * **version:** HexChat version number.
* **xchatdir:** HexChat config directory e.g.: "~/.config/hexchat".
network Current network name or None.
nick Your current nick name.
server Current server name (what the server claims to be) or None if you are not connected.
topic Current channel topic.
version hexchat version number.
xchatdir hexchat config directory e.g.: "~/.config/hexchat".
------------------------------------------------------------------------------------------------
Example: Example:
~~~~~~~~~~ {.python} <pre>
if xchat.get_info("server") is None: if xchat.get_info("server") is None:
xchat.prnt("Not connected!") print "Not connected!"
~~~~~~~~~~ </pre>
#### xchat.get_prefs(name)
Retrieve the xchat setting information specified by the `name` string, #### xchat.get\_prefs(name)
Retrieve the HexChat setting information specified by the `name` string,
as available by the `/set` command. For example: as available by the `/set` command. For example:
~~~~~~~~~~ {.python} <pre>
print "Current preferred nick:", xchat.get_prefs("irc_nick1") print "Current preferred nick:", xchat.get_prefs("irc_nick1")
~~~~~~~~~~ </pre>
#### xchat.get_list(type)
#### xchat.get\_list(type)
With this function you may retrieve a list containing the selected With this function you may retrieve a list containing the selected
information from the current context, like a DCC list, a channel list, a information from the current context, like a DCC list, a channel list, a
user list, etc. Each list item will have its attributes set dynamically user list, etc. Each list item will have its attributes set dynamically
depending on the information provided by the list type. depending on the information provided by the list type.
The example below is a rewrite of the example provided with xchat's The example below is a rewrite of the example provided with HexChat's
plugin API documentation. It prints a list of every DCC transfer plugin API documentation. It prints a list of every DCC transfer
happening at the moment. Notice how similar the interface is to the C happening at the moment. Notice how similar the interface is to the C
API provided by xchat. API provided by xchat.
~~~~~~~~~~ {.python} <pre>
list = xchat.get_list("dcc") list = xchat.get_list("dcc")
if list: if list:
print "--- DCC LIST ------------------" print "--- DCC LIST ------------------"
print "File To/From KB/s Position" print "File To/From KB/s Position"
for i in list: for i in list:
print "%6s %10s %.2f %d" % (i.file, i.nick, i.cps/1024, i.pos) print "%6s %10s %.2f %d" % (i.file, i.nick, i.cps/1024, i.pos)
~~~~~~~~~~ </pre>
Below you will find what each list type has to offer. Below you will find what each list type has to offer.
This information was This information was taken from HexChat's plugin documentation. You may find any types not
taken from xchat's plugin documentation. You may find any types not listed here, if they exist at all, in an updated HexChat documentation.
listed here, if they exist at all, in an updated xchat documentation. Any list types accepted by HexChat should be dynamically accepted by the
Any list types accepted by xchat should be dynamically accepted by the
Python plugin interface. Python plugin interface.
##### channels ##### channels
The channels list type gives you access to the channels, queries and The channels list type gives you access to the channels, queries and
their servers. The folloing attributes are available in each list item: their servers. The folloing attributes are available in each list item:
------------------------------------------------------------------- * **channel:** Channel or query name.
*Type* *Description* * **context:** A context object, giving access to that channel/server.
------- ------------------------------------------------------- * **network:** Network name to which this channel belongs.
channel Channel or query name. * **server:** Server name to which this channel belongs.
* **type:** Type of context.
* 1: Server
* 2: Channel
* 3: Dialog
context A context object, giving access to that channel/server.
network Network name to which this channel belongs.
server Server name to which this channel belongs.
type Type of context (1=Server, 2=Channel, 3=Dialog).
-------------------------------------------------------------------
##### dcc ##### dcc
The dcc list type gives you access to a list of DCC file transfers. The The dcc list type gives you access to a list of DCC file transfers. The
following attributes are available in each list item: following attributes are available in each list item:
--------------------------------------------------------------------------------------- * **address32:** Address of the remote user (ipv4 address, as an int).
*Type* *Description* * **cps:** Bytes per second (speed).
--------- --------------------------------------------------------------------------- * **destfile:** Destination full pathname.
address32 Address of the remote user (ipv4 address, as an int). * **file:** Filename.
* **nick:** Nickname of person who the file is from/to.
* **port:** TCP port number.
* **pos:** Bytes sent/received.
* **resume:** Point at which this file was resumed (or zero if it was not resumed).
* **size:** File size in bytes.
* **status:** DCC status:
* 0: queued
* 1: active
* 2: failed
* 3: done
* 4: connecting
* 5: aborted
* **type:** DCC type:
* 0: send
* 1: receive
* 2: chatrecv
* 3: chatsend
cps Bytes per second (speed).
destfile Destination full pathname.
file Filename.
nick Nickname of person who the file is from/to.
port TCP port number.
pos Bytes sent/received.
resume Point at which this file was resumed (or zero if it was not resumed).
size File size in bytes.
status DCC status (queued=0, active=1, failed=2, done=3, connecting=4, aborted=5).
type DCC type (send=0, receive=1, chatrecv=2, chatsend=3).
---------------------------------------------------------------------------------------
##### users ##### users
The users list type gives you access to a list of users in the current The users list type gives you access to a list of users in the current
channel. The following attributes are available in each list item: channel. The following attributes are available in each list item:
---------------------------------------------------------------- * **nick:** Nick name.
*Type* *Description* * **host:** Host name in the form user@host (or None, if not known).
------ -------------------------------------------------------- * **prefix:** Prefix character, .e.g: @ or +. Points to a single char.
nick Nick name.
host Host name in the form user@host (or None, if not known).
prefix Prefix character, .e.g: @ or +. Points to a single char.
----------------------------------------------------------------
##### ignore ##### ignore
The ignore list type gives you access to the current ignored list. The The ignore list type gives you access to the current ignored list. The
following attributes are available in each list item: following attributes are available in each list item:
----------------------------------------------------------------------------------------------------------- * **mask:** Ignore mask (for example, "\*!\*@\*.aol.com").
*Type* *Description* * **flags:** Bit field of flags:
----- --------------------------------------------------------------------------------------------------- * 0: private
mask Ignore mask (for example, "*!*@*.aol.com"). * 1: notice
* 2: channel
* 3: ctcp
* 4: invite
* 5: unignore
* 6: nosave
* 7:dcc
flags Bit field of flags (0=private, 1=notice, 2=channel, 3=ctcp, 4=invite, 5=unignore, 6=nosave, 7=dcc).
-----------------------------------------------------------------------------------------------------------
### Hook functions ### Hook functions
These functions allow one to hook into xchat events. These functions allow one to hook into xchat events.
#### Priorities #### Priorities
When a priority keyword parameter is accepted, it means that this When a priority keyword parameter is accepted, it means that this
callback may be hooked with five different priorities: PRI_HIGHEST, callback may be hooked with five different priorities: PRI\_HIGHEST,
PRI_HIGH, PRI_NORM, PRI_LOW, and PRI_LOWEST. The usage of these PRI\_HIGH, PRI\_NORM, PRI\_LOW, and PRI\_LOWEST. The usage of these
constants, which are available in the xchat module, will define the constants, which are available in the xchat module, will define the
order in which your plugin will be called. Most of the time, you won't order in which your plugin will be called. Most of the time, you won't
want to change its default value (PRI_NORM). want to change its default value (PRI\_NORM).
#### Parameters word and word_eol #### Parameters word and word_eol
@ -313,45 +302,42 @@ These parameters, when available in a callback, are lists of strings
which contain the parameters the user entered for the particular which contain the parameters the user entered for the particular
command. For example, if you executed: command. For example, if you executed:
> /command NICK Hi there! <pre>
/command NICK Hi there!
</pre>
* **word[0]** is `command`
* **word[1]** is `NICK`
* **word[2]** is `Hi`
* **word[3]** is `there!`
* **word\_eol[0]** is `command NICK Hi there!`
* **word\_eol[1]** is `NICK Hi there!`
* **word\_eol[2]** is `Hi there!`
* **word\_eol[3]** is `there!`
- **word[0]** is `command`
- **word[1]** is `NICK`
- **word[2]** is `Hi`
- **word[3]** is `there!`
- **word_eol[0]** is `command NICK Hi there!`
- **word_eol[1]** is `NICK Hi there!`
- **word_eol[2]** is `Hi there!`
- **word_eol[3]** is `there!`
#### Parameter userdata #### Parameter userdata
The parameter userdata, if given, allows you to pass a custom object to The parameter userdata, if given, allows you to pass a custom object to
your callback. your callback.
#### Callback return constants (EAT_*) #### Callback return constants (EAT\_*)
When a callback is supposed to return one of the EAT_* macros, it is When a callback is supposed to return one of the EAT\_\* macros, it is
able control how xchat will proceed after the callback returns. These able control how xchat will proceed after the callback returns. These
are the available constants, and their meanings: are the available constants, and their meanings:
--------------------------------------------------------- * **EAT_PLUGIN:** Don't let any other plugin receive this event.
*Constant* *Description* * **EAT_XCHAT:** Don't let xchat treat this event as usual.
----------- --------------------------------------------- * **EAT_ALL:** Eat the event completely.
EAT_PLUGIN Don't let any other plugin receive this event. * **EAT_NONE:** Let everything happen as usual.
EAT_XCHAT Don't let xchat treat this event as usual.
EAT_ALL Eat the event completely.
EAT_NONE Let everything happen as usual.
---------------------------------------------------------
Returning `None` is the same as returning `EAT_NONE`. Returning `None` is the same as returning `EAT_NONE`.
#### xchat.hook_command(name, callback, userdata=None, priority=PRI_NORM, help=None)
This function allows you to hook into the name xchat command. It means #### xchat.hook\_command(name, callback, userdata=None, priority=PRI\_NORM, help=None)
This function allows you to hook into the name HexChat command. It means
that everytime you type `/name ...`, `callback` will be called. that everytime you type `/name ...`, `callback` will be called.
Parameters `userdata` and `priority` have their meanings explained Parameters `userdata` and `priority` have their meanings explained
above, and the parameter help, if given, allows you to pass a help text above, and the parameter help, if given, allows you to pass a help text
@ -359,7 +345,7 @@ which will be shown when `/help name` is executed. This function returns
a hook handler which may be used in the `xchat.unhook()` function. For a hook handler which may be used in the `xchat.unhook()` function. For
example: example:
~~~~~~~~~~ {.python} <pre>
def onotice_cb(word, word_eol, userdata): def onotice_cb(word, word_eol, userdata):
if len(word) < 2: if len(word) < 2:
print "Second arg must be the message!" print "Second arg must be the message!"
@ -368,31 +354,33 @@ example:
return xchat.EAT_ALL return xchat.EAT_ALL
xchat.hook_command("ONOTICE", onotice_cb, help="/ONOTICE <message> Sends a notice to all ops") xchat.hook_command("ONOTICE", onotice_cb, help="/ONOTICE <message> Sends a notice to all ops")
~~~~~~~~~~ </pre>
You may return one of `EAT_*` constants in the callback, to control You may return one of `EAT_*` constants in the callback, to control
xchat's behavior, as explained above. HexChat's behavior, as explained above.
#### xchat.hook_print(name, callback, userdata=None, priority=PRI_NORM)
#### xchat.hook\_print(name, callback, userdata=None, priority=PRI\_NORM)
This function allows you to register a callback to trap any print This function allows you to register a callback to trap any print
events. The event names are available in the *Edit Event Texts* window. events. The event names are available in the _Edit Event Texts_ window.
Parameters `userdata` and `priority` have their meanings explained Parameters `userdata` and `priority` have their meanings explained
above. This function returns a hook handler which may be used in the above. This function returns a hook handler which may be used in the
`xchat.unhook()` function. For example: `xchat.unhook()` function. For example:
~~~~~~~~~~ {.python} <pre>
def youpart_cb(word, word_eol, userdata): def youpart_cb(word, word_eol, userdata):
print "You have left channel", word[2] print "You have left channel", word[2]
return xchat.EAT_XCHAT # Don't let xchat do its normal printing return xchat.EAT_XCHAT # Don't let xchat do its normal printing
xchat.hook_print("You Part", youpart_cb) xchat.hook_print("You Part", youpart_cb)
~~~~~~~~~~ </pre>
You may return one of `EAT_*` constants in the callback, to control You may return one of `EAT_*` constants in the callback, to control
xchat's behavior, as explained above. HexChat's behavior, as explained above.
#### xchat.hook_server(name, callback, userdata=None, priority=PRI_NORM)
#### xchat.hook\_server(name, callback, userdata=None, priority=PRI\_NORM)
This function allows you to register a callback to be called when a This function allows you to register a callback to be called when a
certain server event occurs. You can use this to trap `PRIVMSG`, certain server event occurs. You can use this to trap `PRIVMSG`,
@ -401,26 +389,27 @@ certain server event occurs. You can use this to trap `PRIVMSG`,
hook handler which may be used in the `xchat.unhook()` function. For hook handler which may be used in the `xchat.unhook()` function. For
example: example:
~~~~~~~~~~ {.python} <pre>
def kick_cb(word, word_eol, userdata): def kick_cb(word, word_eol, userdata):
print "%s was kicked from %s (%s)" % (word[3], word[2], word_eol[4]) print "%s was kicked from %s (%s)" % (word[3], word[2], word_eol[4])
# Don't eat this event, let other plugins and xchat see it too # Don't eat this event, let other plugins and xchat see it too
return xchat.EAT_NONE return xchat.EAT_NONE
xchat.hook_server("KICK", kick_cb) xchat.hook_server("KICK", kick_cb)
~~~~~~~~~~ </pre>
You may return one of `EAT_*` constants in the callback, to control You may return one of `EAT_*` constants in the callback, to control
xchat's behavior, as explained above. HexChat's behavior, as explained above.
#### xchat.hook_timer(timeout, callback, userdata=None)
#### xchat.hook\_timer(timeout, callback, userdata=None)
This function allows you to register a callback to be called every This function allows you to register a callback to be called every
timeout milliseconds. Parameters userdata and priority have their timeout milliseconds. Parameters userdata and priority have their
meanings explained above. This function returns a hook handler which may meanings explained above. This function returns a hook handler which may
be used in the `xchat.unhook()` function. For example: be used in the `xchat.unhook()` function. For example:
~~~~~~~~~~ {.python} <pre>
myhook = None myhook = None
def stop_cb(word, word_eol, userdata): def stop_cb(word, word_eol, userdata):
@ -436,61 +425,69 @@ be used in the `xchat.unhook()` function. For example:
myhook = xchat.hook_timer(5000, timeout_cb) myhook = xchat.hook_timer(5000, timeout_cb)
xchat.hook_command("STOP", stop_cb) xchat.hook_command("STOP", stop_cb)
~~~~~~~~~~ </pre>
If you return a true value from the callback, the timer will be keeped, If you return a true value from the callback, the timer will be keeped,
otherwise it is removed. otherwise it is removed.
#### xchat.hook_unload(timeout, callback, userdata=None)
#### xchat.hook\_unload(timeout, callback, userdata=None)
This function allows you to register a callback to be called when the This function allows you to register a callback to be called when the
plugin is going to be unloaded. Parameters `userdata` and `priority` plugin is going to be unloaded. Parameters `userdata` and `priority`
have their meanings explained above. This function returns a hook have their meanings explained above. This function returns a hook
handler which may be used in the `xchat.unhook()` function. For example: handler which may be used in the `xchat.unhook()` function. For example:
~~~~~~~~~~ {.python} <pre>
def unload_cb(userdata): def unload_cb(userdata):
print "We're being unloaded!" print "We're being unloaded!"
xchat.hook_unload(unload_cb) xchat.hook_unload(unload_cb)
~~~~~~~~~~ </pre>
#### xchat.unhook(handler) #### xchat.unhook(handler)
Unhooks any hook registered with the hook functions above. Unhooks any hook registered with the hook functions above.
### Plugin preferences ### Plugin preferences
You can use pluginpref to easily store and retrieve settings. This was added in the Python plugin version 0.9 You can use pluginpref to easily store and retrieve settings. This was added in the Python plugin version 0.9
#### xchat.set_pluginpref(name, value) #### xchat.set\_pluginpref(name, value)
If neccessary creates a .conf file in the HexChat config dir named addon_python.conf and stores the value in it. Returns 1 on success 0 on failure. If neccessary creates a .conf file in the HexChat config folder named addon\_python.conf and stores the value in it. Returns 1 on success, 0 on failure.
> Note: Until the plugin uses different a conf file per script it's recommened to use 'PluginName-SettingName' to avoid conflicts. > Note: Until the plugin uses different a conf file per script it's recommened to use 'PluginName-SettingName' to avoid conflicts.
#### xchat.get_pluginpref(name)
#### xchat.get\_pluginpref(name)
This will return the value of the variable of that name. If there is none by this name it will return `None`. Numbers are always returned as Integers. This will return the value of the variable of that name. If there is none by this name it will return `None`. Numbers are always returned as Integers.
#### xchat.del_pluginpref(name)
Deletes specified variable. Returns 1 on success (or never existing), 0 on failure. #### xchat.del\_pluginpref(name)
#### xchat.list_pluginpref() Deletes the specified variable. Returns 1 on success (or never existing), 0 on failure.
#### xchat.list\_pluginpref()
Returns a list of all currently set preferences. Returns a list of all currently set preferences.
### Context handling ### Context handling
Below you will find information about how to work with contexts. Below you will find information about how to work with contexts.
#### Context objects #### Context objects
As explained in the Context theory session above, contexts give access As explained in the Context theory session above, contexts give access
to a specific channel/query/server tab of xchat. Every function to a specific channel/query/server tab of xchat. Every function
available in the xchat module will be evaluated in the current context, available in the xchat module will be evaluated in the current context,
which will be specified by xchat itself before passing control to the which will be specified by HexChat itself before passing control to the
module. Sometimes you may want to work in a specific context, and that's module. Sometimes you may want to work in a specific context, and that's
where context objects come into play. where context objects come into play.
@ -500,39 +497,31 @@ You may create a context object using the `xchat.get_context()` or
Each context object offers the following methods: Each context object offers the following methods:
------------------------------------------------------------------------------------------------------------------------- * **context.set():** Changes the current context to be the one represented by this context object.
*Methods* *Description* * **context.prnt(string):** Does the same as the xchat.prnt() function, but in the given context.
---------------------------------------- ----------------------------------------------------------------------------- * **context.emit\_print(event\_name, \*args):** Does the same as the emit\_print() function, but in the given context.
context.set() Changes the current context to be the one represented by this context object. * **context.command(string):** Does the same as the xchat.command() function, but in the given context.
* **context.get\_info(type):** Does the same as the xchat.get\_info() function, but in the given context.
* **context.get\_list(type):** Does the same as the xchat.get\_list() function, but in the given context.
context.prnt(string) Does the same as the xchat.prnt() function, but in the given context.
context.emit_print(event_name, *args) Does the same as the emit_print() function, but in the given context. #### xchat.get\_context()
context.command(string) Does the same as the xchat.command() function, but in the given context.
context.get_info(type) Does the same as the xchat.get_info() function, but in the given context.
context.get_list(type) Does the same as the xchat.get_list() function, but in the given context.
-------------------------------------------------------------------------------------------------------------------------
#### xchat.get_context()
Returns a context object corresponding the the current context. Returns a context object corresponding the the current context.
#### xchat.find_context(server=None, channel=None) #### xchat.find\_context(server=None, channel=None)
Finds a context based on a channel and servername. If `server` is Finds a context based on a channel and servername. If `server` is
`None`, it finds any channel (or query) by the given name. If `channel` `None`, it finds any channel (or query) by the given name. If `channel`
is `None`, it finds the front-most tab/window of the given server. For is `None`, it finds the front-most tab/window of the given server. For
example: example:
~~~~~~~~~~ {.python} <pre>
cnc = xchat.find_context(channel='#conectiva') cnc = xchat.find_context(channel='#conectiva')
cnc.command('whois niemeyer') cnc.command('whois niemeyer')
~~~~~~~~~~ </pre>
* * * * * ***
Original Author: Gustavo Niemeyer [gustavo@niemeyer.net](mailto:gustavo@niemeyer.net) Original Author: Gustavo Niemeyer [gustavo@niemeyer.net](mailto:gustavo@niemeyer.net)