no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+# $EPIC: set_status_format.txt,v 1.8 2007/05/20 01:19:15 jnelson Exp $
+======Synopsis:======
+[[set]] status_format [<text>]
+======Description:======
+This setting defines the appearance of the data in the status bar.  A
+great deal of information can be displayed in the status bar, such as
+the current time of day, the current channel name and its modes, the
+target of a query, and much more.
+When [[set show_status_all]] is OFF (default), some of the expandos
+only appear when the window is the current input window.  Those expandos
+are marked with "(CURRENT)".  If ON, they appear all the time.
+Most of the expandos are macro-replaced with [[set]] variables. These
+expandos are marked with "(SET <variable>)".  Some of these SET values
+can contain the expando and will get data put in there.  These sub-expanded
+SETs are marked with "wrapper".
+**PLEASE NOTE** that the status_format is not reversed, like it is in ircII
+and BitchX.  If you want a reverse status bar, you need to start your status
+format out with a reverse character (control-V).
+======List of status bar expandos======
+All expandos are case sensitive, and by convention are uppercase.
+Each header tells you
+  - The name of the expando
+  - Whether it shows only on the current input window (//CURRENT//)
+  - Whether it shows a string you can configure ([[set]] link)
+  - Whether it has a sub-expansion value that is substituted into the linked [[set]] variable using the same expando. (see below)
+> %A  (CURRENT, [[SET STATUS_AWAY]])
+This expands when you are [[AWAY]].  If you are connected to only
+one server, this appears in the current window.  If you are connected
+to multiple servers, this appears in all windows.
+> %B  ([[SET STATUS_HOLD_LINES]], wrapper)
+This expands if you have lines in your scrollback that you have
+never seen ("held lines").  This sub-expansion value is the number of
+lines that you have never seen.  It is updated every [[window hold_interval]]
+or [[set hold_interval]] lines.
+> %C  ([[SET STATUS_CHANNEL]], wrapper)
+This expands when you are on a channel.  The sub-expansion value is
+the current channel name:
+* But if [[set hide_private_channels]] is ON, and the channel mode includes
++p or +s, "*private*" is used instead.
+* But if [[set channel_name_width]] is > 0, and the channel name is longer
+than this value, it is chopped off to this length.
+> %D  (CURRENT)
+This expands to information about your current file transfer when
+you have a [[DCC SEND]] or [[DCC GET]] in progress, and when the window's
+level includes DCC, or if this is the current input window and
+[[SET CURRENT_WINDOW_LEVEL]] includes DCC.
+> %{1}D
+This expands to information about your current file transfer when you
+have a [[DCC SEND]] or [[DCC GET]] in progress.  It unconditionally appears
+in every window.
+> %E
+This expands to the current activity string for the window.  I need to
+document this more fully in [[window_activity_handling]].
+> %F  (CURRENT, [[SET STATUS_NOTIFY]], wrapper)
+If you /[[WINDOW NOTIFY]] ON, a window, then hide it, and output occurs
+to one of the levels in the hidden window's [[WINDOW NOTIFY_LEVEL]],
+the window will "notify" you that it has output.  The sub-expansion
+value is a comma-separated list of the window refnums that are
+"notifying".
+> %{1}F (CURRENT, [[SET STATUS_NOTIFY]], wrapper)
+Just like %F, this gives you a list of notifying hidden windows,
+but if the window has a name, the name is used instead of its refnum.
+> %H  ([[SET STATUS_HOLD]])
+This expands if you have lines in your scrollback that you have
+never seen ("held lines").
+> %I  (CURRENT, [[SET STATUS_INSERT]])
+This expands when [[SET INSERT_MODE]] is ON.
+> %K  ([[SET STATUS_SCROLLBACK]])
+This expands when you are browsing the scrollback in this window.
+It can be helpful to use this because any new output to your window
+is "held" when you are in scrollback mode, and this gives you a
+visual clue that you haven't existed scrollback mode yet.
+> %{1}K
+This expands when you are browsing the scrollback in this window.
+It expands to "(Scroll: <num1> of <num2>)" where <num1> is how far
+the top of your display is from the bottom of the scrollback buffer
+(including any lines being held), and <num2> is how many lines total
+are in your scrollback buffer (including any lines being held).
+> %L  ([[SET STATUS_CPU_SAVER]], wrapper)
+This expands when you are in [[bind_cpu_saver|CPU SAVER]] mode.  The
+sub-expansion value is the literal string "CPU".
+> %M  (CURRENT, [[SET STATUS_MAIL]], wrapper)
+This expands whenever [[SET MAIL]] is not 0 and you have mail in
+your inbox.  EPIC only supports mbox right now.  If [[SET MAIL]] is 1,
+the sub-expression value is the empty string.  If [[SET MAIL]] is 2,
+the sub-expression value is the number of emails in your inbox.
+> %N  ([[SET STATUS_NICKNAME]], wrapper)
+This always expands.  The sub-expansion value is the nickname you
+are using on the window's server.  If the window is not connected
+to a server, the sub-expansion value is "<invalid server>".  If the
+window is connected to a disconnected server, the sub-expansion
+value is "<not registered yet>".
+> %O  (CURRENT, [[SET STATUS_OVERWRITE]])
+This expands when [[SET INSERT_MODE]] is OFF.
+> %P
+This is an expando which is used by the developers to display
+debugging information without doing any screen output.  There is
+no point in documenting it since it changes frequently.
+> %Q  ([[SET STATUS_QUERY]], wrapper)
+This expands whenever you have a [[QUERY]] in this window.  The
+sub-expansion value is target you are querying.
+> %R
+This always expands to the window's name, if it has one, and to
+the window's refnum, if it does not have a name.
+> %{1}R
+This always expands to the window's refnum.
+> %S ([[SET STATUS_SERVER]], wrapper)
+This always expands except when you are connected to exactly one server. 1) If
+the window is not connected to a server, it expands to "No Server".  2) If
+[[serverourname|our name]] for the server is an IP address, the sub-expansion
+value is the IP address. 3) Otherwise, the sub-expansion value is the first
+segment of [[serverourname|our name]] that doesn't start with "irc". The
+sub-expansion value is truncated to 60 chars if it is too long. As an example,
+if you are connected to "irc.choomba.com", then %S is "choomba", and if you are
+connected to "192.168.1.101" then %S is "192.168.1.101" and if you are
+connected to "zen.buddha.com" then
+%S is "zen".  I hope this makes sense!
+> %{1}S ([[SET STATUS_SERVER]], wrapper)
+This is just like %S, but it always expands, even when you are connected
+to exactly one server.
+> %{2}S ([[SET STATUS_SERVER]], wrapper)
+This is just like %{1}S, but the sub-expansion value is the full
+[[serverourname|our name]] of the server, and is not chopped into segments.
+> %{3}S ([[SET STATUS_SERVER]], wrapper)
+This is just like %{1}S, but the sub-expansion value is the [[servergroup|group
+name]] of the server.
+> %T  (CURRENT, [[SET STATUS_CLOCK]], wrapper)
+This expands if [[SET CLOCK]] is ON.
+  - If [[SET CLOCK_FORMAT]] is set, the sub-expansion value is the current time formatted with strftime() using [[SET CLOCK_FORMAT]].
+  - If [[SET CLOCK_FORMAT]] is unset and [[SET CLOCK_24HOUR]] is ON, then the sub-expansion value is the current time in 24 hour time.
+  - Otherwise, the sub-expansion value is the current time in 12 hour (AM-PM) time.
+> %{1}T
+This expands to the string "TEST".  If you don't see this on the
+status bar when you use this expando, your epic version doesn't
+support status expando maps.
+> %U
+[see below]
+> %V  (CURRENT)
+This expands to the client's version string ($V)
+> %W  (CURRENT, [[set status_window]])
+This expands if there is more than one window on the screen, and
+this window is the current input window.  This expando should be
+used as a visual cue that this window is the current input window
+when you are using a split screen.
+> %{1}W  ([[SET STATUS_NOSWAP]], wrapper)
+This expands if [[window swappable]] is OFF.
+> %{2}W  ([[set status_window]])
+This expands on every window on every screen.
+> %{3}W  (CURRENT, [[set status_window]])
+This expands on the current window, even if there is only one window
+on the screen.
+> %X
+> %Y
+> %Z
+[see below]
+> %#  (CURRENT, [[SET STATUS_UMODE]], wrapper)
+This expands when you have set a user mode on the window's server.
+It alawys expands if you are connected to more than one server.  It
+does not expand if you are not connected to a server in this window.
+The sub-expansion value is the user mode for this server.
+> <noparse>%%</noparse>
+This expands to the literal string "%".  This is necessary for when
+you want to put a % in your status bar.
+> %*  (CURRENT, [[SET STATUS_OPER]])
+This expands when you are an irc operator.
+> %+  ([[SET STATUS_MODE]], wrapper)
+This expands when the current channel has a channel mode.
+This means if you are not on a channel, or the current channel does not
+have a mode, this does not expand.
+The sub-expression value is the current channel's mode, including any
+extra arguments (the channel's limit, the channel's key).
+Because the channel's key might contain a $ and this would interefere with
+[[set status_does_expandos]], special handling is done to protect you.
+> %{1}+ ([[SET STATUS_MODE]], wrapper)
+This is like %+, but it expands even when the current channel doesn't have a mode.
+> %{2}+	([[SET STATUS_MODE]], wrapper)
+This is like %+, but doesn't include the extra arguments (limit, key).
+> %{3}+
+This is like %{1}+, but doesn't include the extra arguments (limit, key).
+> %.  ([[WINDOW STATUS_SPECIAL]])
+This expands when you have a [[WINDOW STATUS_SPECIAL]] value.
+> %=  ([[SET STATUS_VOICE]])
+This expands when you are a channel voice for the current channel.
+This does not expand when you are a channel operator for the
+current channel.
+> %>
+This special expando begins the "right justify" section.  All text
+that occurs after %> will be right justified on the status bar, but
+if the right justify section is too long to fit on the screen, it
+will be truncated on the right end to fit.
+> %@  ([[SET STATUS_CHANOP]] or [[SET STATUS_HALFOP]])
+This expands when you are either a channel operator or channel half-operator.
+  - If you are a channel operator for the current channel, it expands to [[SET STATUS_CHANOP]]
+  - If you are a channel half-operator for the current channel, it expands to [[SET STATUS_HALFOP]]
+Some servers call the half-operator a //channel helper//
+> %|  ([[SET STATUS_SSL_ON]] or [[SET STATUS_SSL_OFF]])
+This expands to [[SET STATUS_SSL_ON]] when the window's server connection
+is using SSL encryption.  Otherwise, it expands to [[SET STATUS_SSL_OFF]].
+> %U   (CURRENT, [[SET STATUS_USER]])
+> %X   (CURRENT, SET STATUS_USER1)
+> %Y   (CURRENT, SET STATUS_USER2)
+> %Z   (CURRENT, SET STATUS_USER3)
+> %0   (CURRENT, SET STATUS_USER)
+> %1   (CURRENT, SET STATUS_USER1)
+... (%2, %3, %4, %5, %6, %7, %8) ...
+> %9   (CURRENT, SET STATUS_USER9)
+> %{1}0 (CURRENT, SET STATUS_USER10)
+... (%{1}1, %{1}2, %{1}2, %{1}3, %{1}4, %{1}5, %{1}6, %{1}7, %{1}8) ...
+> %{1}9 (CURRENT, SET STATUS_USER19)
+> %{2}0 (SET STATUS_USER20)
+... (%{2}1, %{2}2, %{2}2, %{2}3, %{2}4, %{2}5, %{2}6, %{2}7, %{2}8) ...
+> %{2}9 (SET STATUS_USER29)
+> %{3}0 (SET STATUS_USER30)
+... (%{3}1, %{3}2, %{3}2, %{3}3, %{3}4, %{3}5, %{3}6, %{3}7, %{3}8) ...
+> %{3}9 (SET STATUS_USER39)
+These always expand.
+======Syntax of Status Expandos======
+All expandos have a "map" level, and the level is specified with the
+syntax %{map}expando, where "map" is a number and "expando" is a single
+character.  If you don't give a "map", map 0 is assumed.  In the above
+lists, you will see that most of the expandos are in map 0.  But to be
+absolutely clear about this, %{0}S and %S are the same thing.
+======Duplicated expandos======
+Note that [[SET STATUS_USER]] - SET STATUS_USER3 have 2 (two) expandos
+associated with them.  This is for convenience, as the remaining
+user-definable expandos are only referenced by number.  The duplicates
+cannot be set independently. The [[set status user|STATUS_USER]] expandos defined in the
+map level of their respective tens-digit. This is especially important for
+those above 9, which *must* have their map level specified.  For example,
+STATUS_USER15 would be specified as %{1}5.
+======Repeated Last Character======
+The normal behavior is to cause the last character in the status bar to
+repeat until the the of the line.  This can be disabled by turning on
+the [[set STATUS_NO_REPEAT]] setting, or by making the last character in
+[[set STATUS_FORMAT]] a space.  No repetition is done if the right-alignment
+expando is used.
+======Double Status Bar======
+If the current window happens to have [[window DOUBLE]] turned on
+(double status line), then this setting is ignored, in favor of
+[[set STATUS_FORMAT1]] and [[set STATUS_FORMAT2]].  The former applies
+to the top line, the latter to the bottom.  They are otherwise the same
+as [[set STATUS_FORMAT]].
+======Window-specific status formats======
+You can overrule [[set status_format]], [[set status_format1]], and
+[[set status_format2]] on a per-window basis by setting that window's
+[[window status_format]], [[window status_format1]], or
+[[window status_format2]] value.
+======Sub-expansion values======
+Historically, ircII does not permit you to put alias expandos in your
+status format.  This is a problem because a lot of the things that you
+want to put on your status bar are only available as alias expandos.
+So status expandos have a way to "sub-expand", allowing you to put a
+variable in the status bar.
+The way this works is by using the status expando in the linked set value.
+For example, %Q expands to [[set status_query]] when you have a query.
+But how do you put the current query target in [[set status_query]]?  It
+can change dynamically.  You do it by including %Q.
+	/[[SET STATUS_QUERY]]  (Query: %Q)
+So for any expando in the above list that says //wrapper//, you are
+expected to put that expando in the corresponding set value, where the
+//sub-expansion// value will be put.
+I hope this makes sense.  Check out the set status_* variables to see
+how each of them link back to their corresponding status expando.
+======Examples:======
+A common status bar configuration:
+  /[[set status_format]] *%R* %H%=%@%N%*%S%# %C%+%Q %O%M%A%T%W %D *
+A common doubled status bar configuration:
+  /[[set status_format1]] *%R* %H%=%@%N%*%S%# %C%+%Q %O%M%A%T %D *
+  /[[set status_format2]] %W %X %Y $Z *