# $EPIC: set_status_format.txt,v 1.8 2007/05/20 01:19:15 jnelson Exp $ ======Synopsis:====== [[set]] status_format [] ======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 )". 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: of )" where is how far the top of your display is from the bottom of the scrollback buffer (including any lines being held), and 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 "". If the window is connected to a disconnected server, the sub-expansion value is "". > %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. > %% 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 *