<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Reference</title>
<link rel="stylesheet" href="../luadoc.css" type="text/css" />
<!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<div id="navigation">
<h1>LuaDoc</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<!-- Module list -->
<h1>Modules</h1>
<ul>
<li>
<a href="../modules/awesome.html">awesome</a>
</li>
<li>
<a href="../modules/awful.html">awful</a>
</li>
<li>
<a href="../modules/awful.autofocus.html">awful.autofocus</a>
</li>
<li>
<a href="../modules/awful.button.html">awful.button</a>
</li>
<li>
<a href="../modules/awful.client.html">awful.client</a>
</li>
<li>
<a href="../modules/awful.completion.html">awful.completion</a>
</li>
<li>
<a href="../modules/awful.dbus.html">awful.dbus</a>
</li>
<li>
<a href="../modules/awful.hooks.html">awful.hooks</a>
</li>
<li>
<a href="../modules/awful.key.html">awful.key</a>
</li>
<li>
<a href="../modules/awful.layout.html">awful.layout</a>
</li>
<li>
<a href="../modules/awful.layout.suit.html">awful.layout.suit</a>
</li>
<li>
<a href="../modules/awful.layout.suit.fair.html">awful.layout.suit.fair</a>
</li>
<li>
<a href="../modules/awful.layout.suit.floating.html">awful.layout.suit.floating</a>
</li>
<li>
<a href="../modules/awful.layout.suit.magnifier.html">awful.layout.suit.magnifier</a>
</li>
<li>
<a href="../modules/awful.layout.suit.max.html">awful.layout.suit.max</a>
</li>
<li>
<a href="../modules/awful.layout.suit.spiral.html">awful.layout.suit.spiral</a>
</li>
<li>
<a href="../modules/awful.layout.suit.tile.html">awful.layout.suit.tile</a>
</li>
<li>
<a href="../modules/awful.menu.html">awful.menu</a>
</li>
<li>
<a href="../modules/awful.mouse.html">awful.mouse</a>
</li>
<li>
<a href="../modules/awful.mouse.finder.html">awful.mouse.finder</a>
</li>
<li>
<a href="../modules/awful.placement.html">awful.placement</a>
</li>
<li>
<a href="../modules/awful.prompt.html">awful.prompt</a>
</li>
<li>
<a href="../modules/awful.remote.html">awful.remote</a>
</li>
<li>
<a href="../modules/awful.rules.html">awful.rules</a>
</li>
<li>
<a href="../modules/awful.screen.html">awful.screen</a>
</li>
<li>
<a href="../modules/awful.startup_notification.html">awful.startup_notification</a>
</li>
<li><strong>awful.tag</strong></li>
<li>
<a href="../modules/awful.titlebar.html">awful.titlebar</a>
</li>
<li>
<a href="../modules/awful.tooltip.html">awful.tooltip</a>
</li>
<li>
<a href="../modules/awful.util.html">awful.util</a>
</li>
<li>
<a href="../modules/awful.wibox.html">awful.wibox</a>
</li>
<li>
<a href="../modules/awful.widget.html">awful.widget</a>
</li>
<li>
<a href="../modules/awful.widget.button.html">awful.widget.button</a>
</li>
<li>
<a href="../modules/awful.widget.common.html">awful.widget.common</a>
</li>
<li>
<a href="../modules/awful.widget.graph.html">awful.widget.graph</a>
</li>
<li>
<a href="../modules/awful.widget.launcher.html">awful.widget.launcher</a>
</li>
<li>
<a href="../modules/awful.widget.layout.html">awful.widget.layout</a>
</li>
<li>
<a href="../modules/awful.widget.layout.default.html">awful.widget.layout.default</a>
</li>
<li>
<a href="../modules/awful.widget.layout.horizontal.html">awful.widget.layout.horizontal</a>
</li>
<li>
<a href="../modules/awful.widget.layout.vertical.html">awful.widget.layout.vertical</a>
</li>
<li>
<a href="../modules/awful.widget.layoutbox.html">awful.widget.layoutbox</a>
</li>
<li>
<a href="../modules/awful.widget.progressbar.html">awful.widget.progressbar</a>
</li>
<li>
<a href="../modules/awful.widget.prompt.html">awful.widget.prompt</a>
</li>
<li>
<a href="../modules/awful.widget.taglist.html">awful.widget.taglist</a>
</li>
<li>
<a href="../modules/awful.widget.tasklist.html">awful.widget.tasklist</a>
</li>
<li>
<a href="../modules/awful.widget.textclock.html">awful.widget.textclock</a>
</li>
<li>
<a href="../modules/beautiful.html">beautiful</a>
</li>
<li>
<a href="../modules/button.html">button</a>
</li>
<li>
<a href="../modules/client.html">client</a>
</li>
<li>
<a href="../modules/dbus.html">dbus</a>
</li>
<li>
<a href="../modules/image.html">image</a>
</li>
<li>
<a href="../modules/key.html">key</a>
</li>
<li>
<a href="../modules/keygrabber.html">keygrabber</a>
</li>
<li>
<a href="../modules/mouse.html">mouse</a>
</li>
<li>
<a href="../modules/mousegrabber.html">mousegrabber</a>
</li>
<li>
<a href="../modules/naughty.html">naughty</a>
</li>
<li>
<a href="../modules/root.html">root</a>
</li>
<li>
<a href="../modules/screen.html">screen</a>
</li>
<li>
<a href="../modules/selection.html">selection</a>
</li>
<li>
<a href="../modules/tag.html">tag</a>
</li>
<li>
<a href="../modules/timer.html">timer</a>
</li>
<li>
<a href="../modules/wibox.html">wibox</a>
</li>
<li>
<a href="../modules/widget.html">widget</a>
</li>
</ul>
<!-- File list -->
</div><!-- id="navigation" -->
<div id="content">
<h1>Module <code>awful.tag</code></h1>
<p>Useful functions for tag manipulation.</p>
<p><b>Author:</b>
<table class="authors_list">
<tr><td class="name">Julien Danjou <julien@danjou.info></td></tr>
</table>
</p>
<p>Copyright© 2008 Julien Danjou</p>
<p><small><b>Release:</b> v3.4.15 </small></p>
<h2>Functions</h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#add">add</a> (name, props)</td>
<td class="summary">Add a tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#attached_add_signal">attached_add_signal</a> (screen, ...)</td>
<td class="summary">Add a signal to all attached tag and all tag that will be attached in the future.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#delete">delete</a> (target_tag, fallback_tag)</td>
<td class="summary">Delete a tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#find_fallback">find_fallback</a> (screen, invalids, target)</td>
<td class="summary">Find a suitable fallback tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#getdata">getdata</a> (tag)</td>
<td class="summary">Get tag data table.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#geticon">geticon</a> (tag, t)</td>
<td class="summary">Get the tag icon </td>
</tr>
<tr>
<td class="name" nowrap><a href="#getidx">getidx</a> (query_tag)</td>
<td class="summary">Get a tag's index in the screen[]:tags() table.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#getmwfact">getmwfact</a> (t)</td>
<td class="summary">Get master width factor.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#getncol">getncol</a> (t)</td>
<td class="summary">Get number of column windows.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#getnmaster">getnmaster</a> (t)</td>
<td class="summary">Get the number of master windows.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#getproperty">getproperty</a> (tag, prop)</td>
<td class="summary">Get a tag property.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#history.restore">history.restore</a> (screen, idx)</td>
<td class="summary">Revert tag history.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#history.update">history.update</a> (obj)</td>
<td class="summary">Update the tag history.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#incmwfact">incmwfact</a> (add, t)</td>
<td class="summary">Increase master width factor.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#incncol">incncol</a> (add, t)</td>
<td class="summary">Increase number of column windows.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#incnmaster">incnmaster</a> (add, t)</td>
<td class="summary">Increase the number of master windows.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#move">move</a> (new_index, target_tag)</td>
<td class="summary">Move a tag to an absolute position in the screen[]:tags() table.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#new">new</a> (names, screen, layout)</td>
<td class="summary">Create a set of tags and attach it to a screen.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#selected">selected</a> (s)</td>
<td class="summary">Return only the first visible tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#selectedlist">selectedlist</a> (s)</td>
<td class="summary">Return a table with all visible tags </td>
</tr>
<tr>
<td class="name" nowrap><a href="#seticon">seticon</a> (icon, tag)</td>
<td class="summary">Set the tag icon </td>
</tr>
<tr>
<td class="name" nowrap><a href="#setmwfact">setmwfact</a> (mwfact, t)</td>
<td class="summary">Set master width factor.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#setncol">setncol</a> (ncol, t)</td>
<td class="summary">Set number of column windows.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#setnmaster">setnmaster</a> (nmaster, t)</td>
<td class="summary">Set the number of master windows.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#setproperty">setproperty</a> (tag, prop, value)</td>
<td class="summary">Set a tag property.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#viewidx">viewidx</a> (i, screen)</td>
<td class="summary">View a tag by its taglist index.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#viewmore">viewmore</a> (tags, screen)</td>
<td class="summary">View only a set of tags.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#viewnext">viewnext</a> (screen)</td>
<td class="summary">View next tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#viewnone">viewnone</a> (screen, Optional)</td>
<td class="summary">View no tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#viewonly">viewonly</a> (t)</td>
<td class="summary">View only a tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#viewprev">viewprev</a> (screen)</td>
<td class="summary">View previous tag.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#viewtoggle">viewtoggle</a> (t, tag)</td>
<td class="summary">Toggle selection of a tag </td>
</tr>
<tr>
<td class="name" nowrap><a href="#withcurrent">withcurrent</a> (c, startup)</td>
<td class="summary">Tag a client with the set of current tags.</td>
</tr>
</table>
<br/>
<br/>
<h2><a name="functions"></a>Functions</h2>
<dl class="function">
<dt><a name="add"></a><strong>add</strong> (name, props)</dt>
<dd>
Add a tag.
<h3>Parameters</h3>
<ul>
<li>
name: The tag name, a string
</li>
<li>
props: The tags properties, a table
</li>
</ul>
<h3>Return value:</h3>
The created tag
</dd>
<dt><a name="attached_add_signal"></a><strong>attached_add_signal</strong> (screen, ...)</dt>
<dd>
Add a signal to all attached tag and all tag that will be attached in the future. When a tag is detach from the screen, its signal is removed.
<h3>Parameters</h3>
<ul>
<li>
screen: The screen concerned, or all if nil.
</li>
<li>
...:
</li>
</ul>
</dd>
<dt><a name="delete"></a><strong>delete</strong> (target_tag, fallback_tag)</dt>
<dd>
Delete a tag.
<h3>Parameters</h3>
<ul>
<li>
target_tag: Optional tag object to delete. [selected()]
</li>
<li>
fallback_tag: Tag to assign stickied tags to. [~selected()]
</li>
</ul>
<h3>Return value:</h3>
Returns true if the tag is successfully deleted, nil otherwise. If there are no clients exclusively on this tag then delete it. Any stickied clients are assigned to the optional 'fallback_tag'. If after deleting the tag there is no selected tag, try and restore from history or select the first tag on the screen.
</dd>
<dt><a name="find_fallback"></a><strong>find_fallback</strong> (screen, invalids, target)</dt>
<dd>
Find a suitable fallback tag.
<h3>Parameters</h3>
<ul>
<li>
screen: The screen number to look for a tag on. [mouse.screen]
</li>
<li>
invalids:
</li>
<li>
target: A table of tags we consider unacceptable. [selectedlist(scr)]
</li>
</ul>
</dd>
<dt><a name="getdata"></a><strong>getdata</strong> (tag)</dt>
<dd>
Get tag data table.
<h3>Parameters</h3>
<ul>
<li>
tag: The Tag.
</li>
</ul>
<h3>Return value:</h3>
The data table.
</dd>
<dt><a name="geticon"></a><strong>geticon</strong> (tag, t)</dt>
<dd>
Get the tag icon
<h3>Parameters</h3>
<ul>
<li>
tag:
</li>
<li>
t: the tag
</li>
</ul>
</dd>
<dt><a name="getidx"></a><strong>getidx</strong> (query_tag)</dt>
<dd>
Get a tag's index in the screen[]:tags() table.
<h3>Parameters</h3>
<ul>
<li>
query_tag: The tag object to find. [selected()]
</li>
</ul>
<h3>Return value:</h3>
The index of the tag, nil if the tag is not found.
</dd>
<dt><a name="getmwfact"></a><strong>getmwfact</strong> (t)</dt>
<dd>
Get master width factor.
<h3>Parameters</h3>
<ul>
<li>
t: Optional tag.
</li>
</ul>
</dd>
<dt><a name="getncol"></a><strong>getncol</strong> (t)</dt>
<dd>
Get number of column windows.
<h3>Parameters</h3>
<ul>
<li>
t: Optional tag.
</li>
</ul>
</dd>
<dt><a name="getnmaster"></a><strong>getnmaster</strong> (t)</dt>
<dd>
Get the number of master windows.
<h3>Parameters</h3>
<ul>
<li>
t: Optional tag.
</li>
</ul>
</dd>
<dt><a name="getproperty"></a><strong>getproperty</strong> (tag, prop)</dt>
<dd>
Get a tag property.
<h3>Parameters</h3>
<ul>
<li>
tag: The tag.
</li>
<li>
prop: The property name.
</li>
</ul>
<h3>Return value:</h3>
The property.
</dd>
<dt><a name="history.restore"></a><strong>history.restore</strong> (screen, idx)</dt>
<dd>
Revert tag history.
<h3>Parameters</h3>
<ul>
<li>
screen: The screen number.
</li>
<li>
idx: Index in history. Defaults to "previous" which is a special index toggling between last two selected sets of tags. Number (eg 1) will go back to the given index in history.
</li>
</ul>
</dd>
<dt><a name="history.update"></a><strong>history.update</strong> (obj)</dt>
<dd>
Update the tag history.
<h3>Parameters</h3>
<ul>
<li>
obj: Screen object.
</li>
</ul>
</dd>
<dt><a name="incmwfact"></a><strong>incmwfact</strong> (add, t)</dt>
<dd>
Increase master width factor.
<h3>Parameters</h3>
<ul>
<li>
add: Value to add to master width factor.
</li>
<li>
t:
</li>
</ul>
</dd>
<dt><a name="incncol"></a><strong>incncol</strong> (add, t)</dt>
<dd>
Increase number of column windows.
<h3>Parameters</h3>
<ul>
<li>
add: Value to add to number of column windows.
</li>
<li>
t:
</li>
</ul>
</dd>
<dt><a name="incnmaster"></a><strong>incnmaster</strong> (add, t)</dt>
<dd>
Increase the number of master windows.
<h3>Parameters</h3>
<ul>
<li>
add: Value to add to number of master windows.
</li>
<li>
t:
</li>
</ul>
</dd>
<dt><a name="move"></a><strong>move</strong> (new_index, target_tag)</dt>
<dd>
Move a tag to an absolute position in the screen[]:tags() table.
<h3>Parameters</h3>
<ul>
<li>
new_index: Integer absolute position in the table to insert.
</li>
<li>
target_tag:
</li>
</ul>
</dd>
<dt><a name="new"></a><strong>new</strong> (names, screen, layout)</dt>
<dd>
Create a set of tags and attach it to a screen.
<h3>Parameters</h3>
<ul>
<li>
names: The tag name, in a table
</li>
<li>
screen: The tag screen, or 1 if not set.
</li>
<li>
layout: The layout or layout table to set for this tags by default.
</li>
</ul>
<h3>Return value:</h3>
A table with all created tags.
</dd>
<dt><a name="selected"></a><strong>selected</strong> (s)</dt>
<dd>
Return only the first visible tag.
<h3>Parameters</h3>
<ul>
<li>
s: Screen number.
</li>
</ul>
</dd>
<dt><a name="selectedlist"></a><strong>selectedlist</strong> (s)</dt>
<dd>
Return a table with all visible tags
<h3>Parameters</h3>
<ul>
<li>
s: Screen number.
</li>
</ul>
<h3>Return value:</h3>
A table with all selected tags.
</dd>
<dt><a name="seticon"></a><strong>seticon</strong> (icon, tag)</dt>
<dd>
Set the tag icon
<h3>Parameters</h3>
<ul>
<li>
icon: the icon to set, either path or image object
</li>
<li>
tag: the tag
</li>
</ul>
</dd>
<dt><a name="setmwfact"></a><strong>setmwfact</strong> (mwfact, t)</dt>
<dd>
Set master width factor.
<h3>Parameters</h3>
<ul>
<li>
mwfact: Master width factor.
</li>
<li>
t:
</li>
</ul>
</dd>
<dt><a name="setncol"></a><strong>setncol</strong> (ncol, t)</dt>
<dd>
Set number of column windows.
<h3>Parameters</h3>
<ul>
<li>
ncol: The number of column.
</li>
<li>
t:
</li>
</ul>
</dd>
<dt><a name="setnmaster"></a><strong>setnmaster</strong> (nmaster, t)</dt>
<dd>
Set the number of master windows.
<h3>Parameters</h3>
<ul>
<li>
nmaster: The number of master windows.
</li>
<li>
t: Optional tag.
</li>
</ul>
</dd>
<dt><a name="setproperty"></a><strong>setproperty</strong> (tag, prop, value)</dt>
<dd>
Set a tag property. This properties are internal to awful. Some are used to draw taglist, or to handle layout, etc.
<h3>Parameters</h3>
<ul>
<li>
tag: The tag.
</li>
<li>
prop: The property name.
</li>
<li>
value: The value.
</li>
</ul>
</dd>
<dt><a name="viewidx"></a><strong>viewidx</strong> (i, screen)</dt>
<dd>
View a tag by its taglist index.
<h3>Parameters</h3>
<ul>
<li>
i: The relative index to see.
</li>
<li>
screen: Optional screen number.
</li>
</ul>
</dd>
<dt><a name="viewmore"></a><strong>viewmore</strong> (tags, screen)</dt>
<dd>
View only a set of tags.
<h3>Parameters</h3>
<ul>
<li>
tags: A table with tags to view only.
</li>
<li>
screen: Optional screen number of the tags.
</li>
</ul>
</dd>
<dt><a name="viewnext"></a><strong>viewnext</strong> (screen)</dt>
<dd>
View next tag. This is the same as tag.viewidx(1).
<h3>Parameters</h3>
<ul>
<li>
screen: The screen number.
</li>
</ul>
</dd>
<dt><a name="viewnone"></a><strong>viewnone</strong> (screen, Optional)</dt>
<dd>
View no tag.
<h3>Parameters</h3>
<ul>
<li>
screen:
</li>
<li>
Optional: screen number.
</li>
</ul>
</dd>
<dt><a name="viewonly"></a><strong>viewonly</strong> (t)</dt>
<dd>
View only a tag.
<h3>Parameters</h3>
<ul>
<li>
t: The tag object.
</li>
</ul>
</dd>
<dt><a name="viewprev"></a><strong>viewprev</strong> (screen)</dt>
<dd>
View previous tag. This is the same a tag.viewidx(-1).
<h3>Parameters</h3>
<ul>
<li>
screen: The screen number.
</li>
</ul>
</dd>
<dt><a name="viewtoggle"></a><strong>viewtoggle</strong> (t, tag)</dt>
<dd>
Toggle selection of a tag
<h3>Parameters</h3>
<ul>
<li>
t:
</li>
<li>
tag: Tag to be toggled
</li>
</ul>
</dd>
<dt><a name="withcurrent"></a><strong>withcurrent</strong> (c, startup)</dt>
<dd>
Tag a client with the set of current tags.
<h3>Parameters</h3>
<ul>
<li>
c: The client to tag.
</li>
<li>
startup: Optional: don't do anything if true.
</li>
</ul>
</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
