StlShowFunc.txt	Showing Functions in the Status Line	Nov 02, 2012

Author:    Charles E. Campbell  <NdrOchip@ScampbellPfamily.AbizM>
           (remove NOSPAM from Campbell's email first)

Copyright: (c) 2004-2012 by Charles E. Campbell		StlShowFunc-copyright
           The VIM LICENSE applies to StlShowFunc.vim,
           ftplugin/c/StlShowFunc_c.vim, ftplugin/dbg/StlShowFunc_dbg.vim,
           ftplugin/matlab/StlShowFunc_m.vim, ftplugin/vim/StlShowFunc_vim.vim,
           (see copyright) except use "StlShowFunc and associated functions"
           instead of "Vim"
No warranty, express or implied.  Use At-Your-Own-Risk.

==============================================================================
1. Contents				StlShowFunc StlShowFunc-contents

    1. Contents.........................................: StlShowFunc
    2. StlShowFunc Manual...............................: StlShowFunc-manual
    3. StlShowFunc History..............................: StlShowFunc-history

==============================================================================
2. StlShowFunc Manual				StlShowFunc-manual

   The StlShowFunc plugin and associated filetype plugins manipulate the
   status line to show the name of the function that the cursor is in.  In
   addition, information on the filename, current line and column, and much
   else is also displayed.  Note that your current statusline option is
   overridden with this plugin, although you can restore it by typing
   	:StlShowFunc!

   If you'd like to change the colorization, define highlighting groups User1,
   User2, and User3 as you wish.  The plugin sets up defaults for them:

	hi User1 ctermfg=white ctermbg=blue guifg=white guibg=blue
	hi User2 ctermfg=cyan  ctermbg=blue guifg=cyan  guibg=blue
	hi User3 ctermfg=green ctermbg=blue guifg=green guibg=blue

   An example of the status line:

 StlShowFunc.vim StlShowFunc() 73,1 Bot Win#1 156x21 Thu May 25, 2006, 01:00:57 PM

  Currently, the cursor is in the StlShowFunc() in StlShowFunc.vim.

   The plugin uses the new (as of vim 7.0) CursorMoved event to trigger a check on
   whether or not the cursor has moved from one function to another.

COMMANDS

   StlShowFunc [lang]    : turn StlShowFunc on for the given language
                           At this time, currently supported languages
			   include:
                              cpp  matlab  c      perl
                              dbg  sh      maple  vim

   StlShowFunc!          : turn off StlShowFunc


HOW IT WORKS

   Tersely, the StlShowFunc utility modifies the 'statusline' option
   to call a function which returns a string based on window number.  It also
   sets up a CursorMoved event which, whenever the cursor is moved, checks to
   see if the enclosing function name has changed and, if it has, sets a
   script and window-associated variable to that function name.

   Here's an overview of StlShowFunc's components:

   plugin/StlShowFunc.vim:

     * sets up a CursorMoved autocommand event so that, when the
       cursor is moved, a check is made to determine if the containing
       function has changed  (ShowFuncSetup())

     * StlSetFunc(), which assigns a function name to a window by changing
       the 'statusline' option.  It clears the association if given a "".

     * StlShowFunc(), which maps the window number to the associated
       StlShowFunc_[language]() function.

   ftplugin/[lang]/StlShowFunc_[lang].vim

     * Provides the function StlShowFunc_[lang](), which determines what
       function the cursor is currently in and calls StlSetFunc(funcname)
       when that function name changes and calls StlSetFunc("") when the
       cursor is not currently inside a function).

     * Invokes  StlShowFunc "[lang]"  to initialize the StlShowFunc system
       for that window and language.

   Here's a more detailed sequence of events involved in the function name
   update:

     * Initially, for supported languages, the ftplugin handler for the language
       invokes StlShowFunc "[lang]", which calls s:ShowFuncSetup().

     * This function then installs a CursorMoved autocommand event, so that when
       the cursor is moved, StlShowFunc_[lang]() is called.  It also calls
       that handler to initialize a variable holding the name of the function
       (if any) that the cursor is in.

     * StlFuncSetup() then sets up the status line option ('stl') to call
       StlShowFunc() (as well as to show other items on the status line).

     * When the cursor is moved, the CursorMoved event is triggered.  This
       event thus invokes StlShowFunc_[lang]()

     * StlShowFunc_[lang]() determines what the name of the function that the
       cursor currently resides in is called.  It calls StlSetFunc(funcname).

     * StlSetFunc(funcname) sets a script variable, s:stlshowfunc_{winnr()},
       to that function name.  These variables are window-oriented, so one
       may have multiple windows opened on the same file, each with their
       own function name associated with their own cursor position.

     * The 'statusline' option also triggers a refresh of the status line.
       The 'statusline' option as set by StlFuncSetup() calls StlShowFunc()
       as part of the status line refresh.

     * The StlShowFunc() returns the string in s:stlshowfunc_{winnr()}.

OPTIONS

							g:stlshowfunc_stlnofunc
     This option lets users override the status line normally given by
     the StlShowFunc plugin with their own preferences.

     Use ":let" to set the following variable which will specify the statusline
     when the cursor is not inside a function:

	stlshowfunc_stlnofunc


							g:stlshowfunc_stlfunc
     This option lets users override the status line normally given by
     the StlShowFunc plugin with their own preferences.

     Use ":let" to set the following variable which will specify the statusline
     when the cursor is inside a function:

	stlshowfunc_stlfunc

    Note that including
	%{StlShowFunc()}
    will result in the status line showing the current function name.
     The first variable (stlshowfunc_stlfunc) is used when StlShowFunc is
     disabled; the second variable is used when StlShowFunc is enabled.

     By default,
	let stlshowfunc_stlnofunc=
	\ '%1*%f%2*\ %{&kmp\ }%h%m%r%0*%=%-14.(%l,%c%V%)%<\ %P\ Win#%{winnr()}\
	\ %{winwidth(0)}x%{winheight(0)}\ %<%{strftime(\"%a\ %b\ %d,\ %Y,\ %I:%M:%S\ \%p\")}'
	let stlshowfunc_stlfunc =
	\ '%1*%f %3*%{StlShowFunc()}%2* %h%m%r%0* %= %-14.(%l,%c%V%)%< %P Win#%{winnr()}
	\ %{winwidth(0)}x%{winheight(0)} %<%{strftime("%a %b %d, %Y, %I:%M:%S %p")}'

==============================================================================
3. StlShowFunc History				StlShowFunc-history {{{1
   v2	Jun 07, 2006  * modified ftplugin/StlShowFunc*.vim files to only update
			the statusline when vim is in normal mode.
	Sep 03, 2008  * stl now set in plugin/StlShowFunc.c
		      * "hi def" now used instead of HLTest().
	May 20, 2009  * cecutil bug fix
	Jun 15, 2009  * made all references to the statusline setting local
	Aug 13, 2009  * StlShowFunc! stopped working somewhere along the line
			(the StlShowFunc command was requiring an argument,
			and obviously :StlShowFunc! doesn't have an argument)
	Jul 09, 2010  * c++ files now avoid loading c/StlShowFunc_c.vim
	              * a test in cpp/StlShowFunc_cpp.vim no longer matches
			things like "if" when embedded in a function name
			when deciding if the function name is a real function.
	Feb 07, 2011  * included support for fortran
	Sep 24, 2012  * included g:stlshowfunc_stlfunc  and g:stlshowfunc_stlnofunc
			options
   v1	May 25, 2006  * initial release

==============================================================================
4. Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker: