# Module `awful.tag`

### Info:

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

## 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) | 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.

## Functions

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

  ### Parameters:

  - new_index Integer absolute position in the table to insert.
  - target_tag The tag that should be moved. If null, the currently selected tag is used.
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.

  ### 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. 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.
tag.history.update (obj)
  Update the tag history.

  ### Parameters:

  - obj Screen object.
tag.history.restore (screen, idx)
  Revert tag history.

  ### Parameters:

  - screen The screen number.
  - 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.
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)
  Tag a client with the set of current tags.

  ### Parameters:

  - c The client to tag.
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.

generated by LDoc 1.4.2