# Module `awful.tag`

### Info:

- Author: Julien Danjou <julien@danjou.info>
- Copyright: 2008 Julien Danjou
- Release: v3.5.1

## Functions

move (new_index, target_tag) | Move a tag to an absolute position in the screen[]:tags() table.
add (name, props) | Add a tag.
new (names, screen, layout) | Create a set of tags and attach it to a screen.
find_fallback (screen, invalids) | Find a suitable fallback tag.
delete (target_tag, fallback_tag) | Delete a tag.
tag.history.update (obj) | Update the tag history.
tag.history.restore (screen, idx) | Revert tag history.
gettags (s) | Get a list of all tags on a screen
setscreen (t, s) | Set a tag's screen
getscreen (t) | Get a tag's screen
selectedlist (s) | Return a table with all visible tags
selected (s) | Return only the first visible tag.
setmwfact (mwfact, t) | Set master width factor.
incmwfact (add, t) | Increase master width factor.
getmwfact (t) | Get master width factor.
setnmaster (nmaster, t) | Set the number of master windows.
getnmaster (t) | Get the number of master windows.
incnmaster (add, t) | Increase the number of master windows.
seticon (icon, _tag) | Set the tag icon
geticon (_tag) | Get the tag icon
setncol (ncol, t) | Set number of column windows.
getncol (t) | Get number of column windows.
incncol (add, t) | Increase number of column windows.
viewnone (Optional) | View no tag.
viewidx (i, screen) | View a tag by its taglist index.
getidx (query_tag) | Get a tag's index in the gettags() table.
viewnext (screen) | View next tag.
viewprev (screen) | View previous tag.
viewonly (t) | View only a tag.
viewmore (tags, screen) | View only a set of tags.
viewtoggle (tag) | Toggle selection of a tag
getdata (tag) | Get tag data table.
getproperty (_tag, prop) | Get a tag property.
setproperty (_tag, prop, value) | Set a tag property.
withcurrent (c, startup) | Tag a client with the set of current tags.
attached_connect_signal (screen) | Add a signal to all attached tag and all tag that will be attached in the future.

## Tables

tag | Useful functions for tag manipulation.

## Functions

move (new_index, target_tag)
  Move a tag to an absolute position in the screen[]:tags() table. selected tag is used.

  ### Parameters:

  - new_index Integer absolute position in the table to insert.
  - target_tag The tag that should be moved. If null, the currently
add (name, props)
  Add a tag.

  ### Parameters:

  - name The tag name, a string
  - props The tags properties, a table

  ### Returns:

  The created tag
new (names, screen, layout)
  Create a set of tags and attach it to a screen.

  ### Parameters:

  - names The tag name, in a table
  - screen The tag screen, or 1 if not set.
  - layout The layout or layout table to set for this tags by default.

  ### Returns:

  A table with all created tags.
find_fallback (screen, invalids)
  Find a suitable fallback tag.

  ### Parameters:

  - screen The screen number to look for a tag on. [mouse.screen]
  - invalids A table of tags we consider unacceptable. [selectedlist(scr)]
delete (target_tag, fallback_tag)
  Delete a tag. 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.

  ### Parameters:

  - target_tag Optional tag object to delete. [selected()]
  - fallback_tag Tag to assign stickied tags to. [~selected()]

  ### Returns:

  Returns true if the tag is successfully deleted, nil otherwise.
tag.history.update (obj)
  Update the tag history.

  ### Parameters:

  - obj Screen object.
tag.history.restore (screen, idx)
  Revert tag history. toggling between last two selected sets of tags. Number (eg 1) will go back to the given index in history.

  ### Parameters:

  - screen The screen number.
  - idx Index in history. Defaults to "previous" which is a special index
gettags (s)
  Get a list of all tags on a screen

  ### Parameters:

  - s Screen number

  ### Returns:

  A table with all available tags
setscreen (t, s)
  Set a tag's screen

  ### Parameters:

  - t tag object
  - s Screen number
getscreen (t)
  Get a tag's screen

  ### Parameters:

  - t tag object

  ### Returns:

  Screen number
selectedlist (s)
  Return a table with all visible tags

  ### Parameters:

  - s Screen number.

  ### Returns:

  A table with all selected tags.
selected (s)
  Return only the first visible tag.

  ### Parameters:

  - s Screen number.
setmwfact (mwfact, t)
  Set master width factor.

  ### Parameters:

  - mwfact Master width factor.
  - t The tag to modify, if null tag.selected() is used.
incmwfact (add, t)
  Increase master width factor.

  ### Parameters:

  - add Value to add to master width factor.
  - t The tag to modify, if null tag.selected() is used.
getmwfact (t)
  Get master width factor.

  ### Parameters:

  - t Optional tag.
setnmaster (nmaster, t)
  Set the number of master windows.

  ### Parameters:

  - nmaster The number of master windows.
  - t Optional tag.
getnmaster (t)
  Get the number of master windows.

  ### Parameters:

  - t Optional tag.
incnmaster (add, t)
  Increase the number of master windows.

  ### Parameters:

  - add Value to add to number of master windows.
  - t The tag to modify, if null tag.selected() is used.
seticon (icon, _tag)
  Set the tag icon

  ### Parameters:

  - icon the icon to set, either path or image object
  - _tag the tag
geticon (_tag)
  Get the tag icon

  ### Parameters:

  - _tag the tag
setncol (ncol, t)
  Set number of column windows.

  ### Parameters:

  - ncol The number of column.
  - t The tag to modify, if null tag.selected() is used.
getncol (t)
  Get number of column windows.

  ### Parameters:

  - t Optional tag.
incncol (add, t)
  Increase number of column windows.

  ### Parameters:

  - add Value to add to number of column windows.
  - t The tag to modify, if null tag.selected() is used.
viewnone (Optional)
  View no tag.

  ### Parameters:

  - Optional screen number.
viewidx (i, screen)
  View a tag by its taglist index.

  ### Parameters:

  - i The relative index to see.
  - screen Optional screen number.
getidx (query_tag)
  Get a tag's index in the gettags() table.

  ### Parameters:

  - query_tag The tag object to find. [selected()]

  ### Returns:

  The index of the tag, nil if the tag is not found.
viewnext (screen)
  View next tag. This is the same as tag.viewidx(1).

  ### Parameters:

  - screen The screen number.
viewprev (screen)
  View previous tag. This is the same a tag.viewidx(-1).

  ### Parameters:

  - screen The screen number.
viewonly (t)
  View only a tag.

  ### Parameters:

  - t The tag object.
viewmore (tags, screen)
  View only a set of tags.

  ### Parameters:

  - tags A table with tags to view only.
  - screen Optional screen number of the tags.
viewtoggle (tag)
  Toggle selection of a tag

  ### Parameters:

  - tag Tag to be toggled
getdata (tag)
  Get tag data table.

  ### Parameters:

  - tag The Tag.

  ### Returns:

  The data table.
getproperty (_tag, prop)
  Get a tag property.

  ### Parameters:

  - _tag The tag.
  - prop The property name.

  ### Returns:

  The property.
setproperty (_tag, prop, value)
  Set a tag property. This properties are internal to awful. Some are used to draw taglist, or to handle layout, etc.

  ### Parameters:

  - _tag The tag.
  - prop The property name.
  - value The value.
withcurrent (c, startup)
  Tag a client with the set of current tags.

  ### Parameters:

  - c The client to tag.
  - startup Optional: don't do anything if true.
attached_connect_signal (screen)
  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.

  ### Parameters:

  - screen The screen concerned, or all if nil.

## Tables

tag
  Useful functions for tag manipulation. awful.tag

  ### Fields:

  - mt

generated by LDoc 1.3