@c-*-texinfo-*-@cThisispartoftheGNUEmacsLispReferenceManual.@cCopyright(C)1990,1991,1992,1993,1994FreeSoftwareFoundation,Inc.@cSeethefileelisp.texiforcopyingconditions.@setfilename../info/windows@nodeWindows,Frames,Buffers,Top@chapterWindowsThischapterdescribesmostofthefunctionsandvariablesrelatedtoEmacswindows.See@ref{Display},forinformationonhowtextisdisplayedinwindows.@menu*BasicWindows::Basicinformationonusingwindows.*SplittingWindows::Splittingonewindowintotwowindows.*DeletingWindows::Deletingawindowgivesitsspacetootherwindows.*SelectingWindows::Theselectedwindowistheonethatyoueditin.*CyclicWindowOrdering::Movingaroundtheexistingwindows.*BuffersandWindows::Eachwindowdisplaysthecontentsofabuffer.*DisplayingBuffers::Higher-leverfunctionsfordisplayingabufferandchoosingawindowforit.*ChoosingWindow::Howtochooseawindowfordisplayingabuffer.*WindowPoint::Eachwindowhasitsownlocationofpoint.*WindowStart::Thedisplay-startpositioncontrolswhichtextison-screeninthewindow.*VerticalScrolling::Movingtextupanddowninthewindow.*HorizontalScrolling::Movingtextsidewaysonthewindow.*SizeofWindow::Accessingthesizeofawindow.*ResizingWindows::Changingthesizeofawindow.*CoordinatesandWindows::Convertingcoordinatestowindows.*WindowConfigurations::Savingandrestoringthestateofthescreen.@endmenu@nodeBasicWindows@sectionBasicConceptsofEmacsWindows@cindexwindow@cindexselectedwindowA@dfn{window}inEmacsisthephysicalareaofthescreeninwhichabufferisdisplayed.ThetermisalsousedtorefertoaLispobjectthatrepresentsthatscreenareainEmacsLisp.Itshouldbeclearfromthecontextwhichismeant.Emacsgroupswindowsintoframes.AframerepresentsanareaofscreenavailableforEmacstouse.Eachframealwayscontainsatleastonewindow,butyoucansubdivideitverticallyorhorizontallyintomultiplenonoverlappingEmacswindows.Ineachframe,atanytime,oneandonlyonewindowisdesignatedas@dfn{selectedwithintheframe}.Theframe's cursor appears in thatwindow. At ant time, one frame is the selected frame; and the windowselected within that frame is @dfn{the selected window}. The selectedwindow'sbufferisusuallythecurrentbuffer(exceptwhen@code{set-buffer}hasbeenused).@xref{CurrentBuffer}.Forpracticalpurposes,awindowexistsonlywhileitisdisplayedinaframe.Onceremovedfromtheframe,thewindowiseffectivelydeletedandshouldnotbeused,@emph{eventhoughtheremaystillbereferencestoit}fromotherLispobjects.Restoringasavedwindowconfigurationistheonlywayforawindownolongeronthescreentocomebacktolife.(@xref{DeletingWindows}.)Eachwindowhasthefollowingattributes:@itemize@bullet@itemcontainingframe@itemwindowheight@itemwindowwidth@itemwindowedgeswithrespecttothescreenorframe@itemthebufferitdisplays@itempositionwithinthebufferattheupperleftofthewindow@itemamountofhorizontalscrolling,incolumns@itempoint@itemthemark@itemhowrecentlythewindowwasselected@enditemize@cindexmultiplewindowsUserscreatemultiplewindowssotheycanlookatseveralbuffersatonce.Lisplibrariesusemultiplewindowsforavarietyofreasons,butmostoftentodisplayrelatedinformation.InRmail,forexample,youcanmovethroughasummarybufferinonewindowwhiletheotherwindowshowsmessagesoneatatimeastheyarereached.Themeaningof``window''inEmacsissimilartowhatitmeansinthecontextofgeneral-purposewindowsystemssuchasX,butnotidentical.TheXWindowSystemplacesXwindowsonthescreen;EmacsusesoneormoreXwindowsasframes,andsubdividesthemintoEmacswindows.WhenyouuseEmacsonacharacter-onlyterminal,Emacstreatsthewholeterminalscreenasoneframe.@cindexterminalscreen@cindexscreenofterminal@cindextiledwindowsMostwindowsystemssupportarbitrarilylocatedoverlappingwindows.Incontrast,Emacswindowsare@dfn{tiled};theyneveroverlap,andtogethertheyfillthewholescreenorframe.BecauseofthewayinwhichEmacscreatesnewwindowsandresizesthem,youcan't createevery conceivable tiling of windows on an Emacs frame. @xref{SplittingWindows}, and @ref{Size of Window}. @xref{Display}, for information on how the contents of thewindow'sbufferaredisplayedinthewindow.@defunwindowpobjectThisfunctionreturns@code{t}if@var{object}isawindow.@enddefun@nodeSplittingWindows@sectionSplittingWindows@cindexsplittingwindows@cindexwindowsplittingThefunctionsdescribedherearetheprimitivesusedtosplitawindowintotwowindows.Twohigherlevelfunctionssometimessplitawindow,butnotalways:@code{pop-to-buffer}and@code{display-buffer}(@pxref{DisplayingBuffers}).Thefunctionsdescribedheredonotacceptabufferasanargument.Thetwo``halves''ofthesplitwindowinitiallydisplaythesamebufferpreviouslyvisibleinthewindowthatwassplit.@deffnCommandsplit-window&optionalwindowsizehorizontalThisfunctionsplits@var{window}intotwowindows.Theoriginalwindow@var{window}remainstheselectedwindow,butoccupiesonlypartofitsformerscreenarea.Therestisoccupiedbyanewlycreatedwindowwhichisreturnedasthevalueofthisfunction.If@var{horizontal}isnon-@code{nil},then@var{window}splitsintotwosidebysidewindows.Theoriginalwindow@var{window}keepstheleftmost@var{size}columns,andgivestherestofthecolumnstothenewwindow.Otherwise,itsplitsintowindowsoneabovetheother,and@var{window}keepstheupper@var{size}linesandgivestherestofthelinestothenewwindow.Theoriginalwindowisthereforetheleft-handorupperofthetwo,andthenewwindowistheright-handorlower.If@var{window}isomittedor@code{nil},thentheselectedwindowissplit.If@var{size}isomittedor@code{nil},then@var{window}isdividedevenlyintotwoparts.(Ifthereisanoddline,itisallocatedtothenewwindow.)When@code{split-window}iscalledinteractively,allitsargumentsare@code{nil}.Thefollowingexamplestartswithonewindowonascreenthatis50lineshighby80columnswide;thenthewindowissplit.@smallexample@group(setqw(selected-window))@result{}#<window8onwindows.texi>(window-edges);@r{Edgesinorder:}@result{}(008050);@r{left--top--right--bottom}@endgroup@group;;@r{Returnswindowcreated}(setqw2(split-windoww15))@result{}#<window28onwindows.texi>@endgroup@group(window-edgesw2)@result{}(0158050);@r{Bottomwindow;};@r{topisline15}@endgroup@group(window-edgesw)@result{}(008015);@r{Topwindow}@endgroup@endsmallexampleThescreenlookslikethis:@smallexample@group__________||line0|w||__________|||line15|w2||__________|line50column0column80@endgroup@endsmallexampleNext,thetopwindowissplithorizontally:@smallexample@group(setqw3(split-windoww35t))@result{}#<window32onwindows.texi>@endgroup@group(window-edgesw3)@result{}(3508015);@r{Leftedgeatcolumn35}@endgroup@group(window-edgesw)@result{}(003515);@r{Rightedgeatcolumn35}@endgroup@group(window-edgesw2)@result{}(0158050);@r{Bottomwindowunchanged}@endgroup@endsmallexample@need3000Now,thescreenlookslikethis:@smallexample@groupcolumn35__________|||line0|w|w3||___|______|||line15|w2||__________|line50column0column80@endgroup@endsmallexampleNormally,Emacsindicatestheborderbetweentwoside-by-sidewindowswithascrollbar(@pxref{XFrameParameters,ScrollBars})or@samp{|}characters.Thedisplaytablecanspecifyalternativebordercharacters;see@ref{DisplayTables}.@enddeffn@deffnCommandsplit-window-verticallysizeThisfunctionsplitstheselectedwindowintotwowindows,oneabovetheother,leavingtheselectedwindowwith@var{size}lines.Thisfunctionissimplyaninterfaceto@code{split-windows}.Hereisthecompletefunctiondefinitionforit:@smallexample@group(defunsplit-window-vertically(&optionalarg)"Split current window into two windows, one above the other."(interactive"P")(split-windownil(andarg(prefix-numeric-valuearg))))@endgroup@endsmallexample@enddeffn@deffnCommandsplit-window-horizontallysizeThisfunctionsplitstheselectedwindowintotwowindowsside-by-side,leavingtheselectedwindowwith@var{size}columns.Thisfunctionissimplyaninterfaceto@code{split-windows}.Hereisthecompletedefinitionfor@code{split-window-horizontally}(exceptforpartofthedocumentationstring):@smallexample@group(defunsplit-window-horizontally(&optionalarg)"Split selected window into two windows, side by side..."(interactive"P")(split-windownil(andarg(prefix-numeric-valuearg))t))@endgroup@endsmallexample@enddeffn@defunone-window-p&optionalno-miniall-framesThisfunctionreturnsnon-@code{nil}ifthereisonlyonewindow.Theargument@var{no-mini},ifnon-@code{nil},meansdon't count theminibuffer even if it is active; otherwise, the minibuffer window isincluded, if active, in the total number of windows, which is comparedagainst one.The argument @var{all-frames} specifies which frames to consider. Hereare the possible values and their meanings:@table @asis@item @code{nil}Count the windows in the selected frame, plus the minibuffer usedby that frame even if it lies in some other frame.@item @code{t}Count all windows in all existing frames.@item @code{visible}Count all windows in all visible frames.@item 0Count all windows in all visible or iconified frames.@item anything elseCount precisely the windows in the selected frame, and no others.@end table@end defun@node Deleting Windows@section Deleting Windows@cindex deleting windowsA window remains visible on its frame unless you @dfn{delete} it bycalling certain functions that delete windows. A deleted window cannotappear on the screen, but continues to exist as a Lisp object untilthere are no references to it. There is no way to cancel the deletionof a window aside from restoring a saved window configuration(@pxref{Window Configurations}). Restoring a window configuration alsodeletes any windows that aren'tpartofthatconfiguration.Whenyoudeleteawindow,thespaceittookupisgiventooneadjacentsibling.(InEmacsversion18,thespacewasdividedevenlyamongallthesiblings.)@cEmacs19feature@defunwindow-live-pwindowThisfunctionreturns@code{nil}if@var{window}isdeleted,and@code{t}otherwise.@strong{Warning:}Erroneousinformationorfatalerrorsmayresultfromusingadeletedwindowasifitwerelive.@enddefun@deffnCommanddelete-window&optionalwindowThisfunctionremoves@var{window}fromthedisplay.If@var{window}isomitted,thentheselectedwindowisdeleted.Anerrorissignaledifthereisonlyonewindowwhen@code{delete-window}iscalled.Thisfunctionreturns@code{nil}.When@code{delete-window}iscalledinteractively,@var{window}defaultstotheselectedwindow.@enddeffn@deffnCommanddelete-other-windows&optionalwindowThisfunctionmakes@var{window}theonlywindowonitsframe,bydeletingtheotherwindowsinthatframe.If@var{window}isomittedor@code{nil},thentheselectedwindowisusedbydefault.Theresultis@code{nil}.@enddeffn@deffnCommanddelete-windows-onbuffer&optionalframeThisfunctiondeletesallwindowsshowing@var{buffer}.Iftherearenowindowsshowing@var{buffer},itdoesnothing.@code{delete-windows-on}operatesframebyframe.Ifaframehasseveralwindowsshowingdifferentbuffers,thenthoseshowing@var{buffer}areremoved,andtheothersexpandtofillthespace.Ifallwindowsinsomeframeareshowing@var{buffer}(includingthecasewherethereisonlyonewindow),thentheframerevertstohavingasinglewindowshowinganotherbufferchosenwith@code{other-buffer}.@xref{TheBufferList}.Theargument@var{frame}controlswhichframestooperateon:@itemize@bullet@itemIfitis@code{nil},operateontheselectedframe.@itemIfitis@code{t},operateonallframes.@itemIfitis@code{visible},operateonallvisibleframes.@item0Ifitis0,operateonallvisibleoriconifiedframes.@itemIfitisaframe,operateonthatframe.@enditemizeThisfunctionalwaysreturns@code{nil}.@enddeffn@nodeSelectingWindows@sectionSelectingWindows@cindexselectingwindowsWhenawindowisselected,thebufferinthewindowbecomesthecurrentbuffer,andthecursorwillappearinit.@defunselected-windowThisfunctionreturnstheselectedwindow.Thisisthewindowinwhichthecursorappearsandtowhichmanycommandsapply.@enddefun@defunselect-windowwindowThisfunctionmakes@var{window}theselectedwindow.Thecursorthenappearsin@var{window}(onredisplay).Thebufferbeingdisplayedin@var{window}isimmediatelydesignatedthecurrentbuffer.Thereturnvalueis@var{window}.@example@group(setqw(next-window))(select-windoww)@result{}#<window65onwindows.texi>@endgroup@endexample@enddefun@defmacsave-selected-windowforms@dots{}Thismacrorecordstheselectedwindow,executes@var{forms}insequence,thenrestorestheearlierselectedwindow.Itdoesnotsaveorrestoreanythingaboutthesizes,arrangementorcontentsofwindows;therefore,ifthe@var{forms}changethem,thechangesarepermanent.@enddefmac@cindexfindingwindowsThefollowingfunctionschooseoneofthewindowsonthescreen,offeringvariouscriteriaforthechoice.@defunget-lru-window&optionalframeThisfunctionreturnsthewindowleastrecently``used''(thatis,selected).Theselectedwindowisalwaysthemostrecentlyusedwindow.Theselectedwindowcanbetheleastrecentlyusedwindowifitistheonlywindow.Anewlycreatedwindowbecomestheleastrecentlyusedwindowuntilitisselected.Aminibufferwindowisneveracandidate.Theargument@var{frame}controlswhichwindowsareconsidered.@itemize@bullet@itemIfitis@code{nil},considerwindowsontheselectedframe.@itemIfitis@code{t},considerwindowsonallframes.@itemIfitis@code{visible},considerwindowsonallvisibleframes.@itemIfitis0,considerwindowsonallvisibleoriconifiedframes.@itemIfitisaframe,considerwindowsonthatframe.@enditemize@enddefun@defunget-largest-window&optionalframeThisfunctionreturnsthewindowwiththelargestarea(heighttimeswidth).Iftherearenoside-by-sidewindows,thenthisisthewindowwiththemostlines.Aminibufferwindowisneveracandidate.Iftherearetwowindowsofthesamesize,thenthefunctionreturnsthewindowthatisfirstinthecyclicorderingofwindows(seefollowingsection),startingfromtheselectedwindow.Theargument@var{frame}controlswhichsetofwindowsareconsidered.See@code{get-lru-window},above.@enddefun@nodeCyclicWindowOrdering@commentnode-name,next,previous,up@sectionCyclicOrderingofWindows@cindexcyclicorderingofwindows@cindexorderingofwindows,cyclic@cindexwindowordering,cyclicWhenyouusethecommand@kbd{C-xo}(@code{other-window})toselectthenextwindow,itmovesthroughallthewindowsonthescreeninaspecificcyclicorder.Foranygivenconfigurationofwindows,thisordernevervaries.Itiscalledthe@dfn{cyclicorderingofwindows}.Thisorderinggenerallygoesfromtoptobottom,andfromlefttoright.Butitmaygodownfirstorgorightfirst,dependingontheorderinwhichthewindowsweresplit.Ifthefirstsplitwasvertical(intowindowsoneaboveeachother),andthenthesubwindowsweresplithorizontally,thentheorderingislefttorightinthetopoftheframe,andthenlefttorightinthenextlowerpartoftheframe,andsoon.Ifthefirstsplitwashorizontal,theorderingistoptobottomintheleftpart,andsoon.Ingeneral,withineachsetofsiblingsatanylevelinthewindowtree,theorderislefttoright,ortoptobottom.@defunnext-window&optionalwindowminibufall-frames@cindexminibufferwindowThisfunctionreturnsthewindowfollowing@var{window}inthecyclicorderingofwindows.Thisisthewindowthat@kbd{C-xo}wouldselectiftypedwhen@var{window}isselected.If@var{window}istheonlywindowvisible,thenthisfunctionreturns@var{window}.Ifomitted,@var{window}defaultstotheselectedwindow.Thevalueoftheargument@var{minibuf}determineswhethertheminibufferisincludedinthewindoworder.Normally,when@var{minibuf}is@code{nil},theminibufferisincludedifitiscurrentlyactive;thisisthebehaviorof@kbd{C-xo}.(Theminibufferwindowisactivewhiletheminibufferisinuse.@xref{Minibuffers}.)If@var{minibuf}is@code{t},thenthecyclicorderingincludestheminibufferwindowevenifitisnotactive.If@var{minibuf}isneither@code{t}nor@code{nil},thentheminibufferwindowisnotincludedevenifitisactive.Theargument@var{all-frames}specifieswhichframestoconsider.Herearethepossiblevaluesandtheirmeanings:@table@asis@item@code{nil}Considerallthewindowsin@var{window}'s frame, plus the minibufferused by that frame even if it lies in some other frame.@item @code{t}Consider all windows in all existing frames.@item @code{visible}Consider all windows in all visible frames. (To get useful results, youmust ensure @var{window} is in a visible frame.)@item 0Consider all windows in all visible or iconified frames.@item anything elseConsider precisely the windows in @var{window}'sframe,andnoothers.@endtableThisexampleassumestherearetwowindows,bothdisplayingthebuffer@samp{windows.texi}:@example@group(selected-window)@result{}#<window56onwindows.texi>@endgroup@group(next-window(selected-window))@result{}#<window52onwindows.texi>@endgroup@group(next-window(next-window(selected-window)))@result{}#<window56onwindows.texi>@endgroup@endexample@enddefun@defunprevious-window&optionalwindowminibufall-framesThisfunctionreturnsthewindowpreceding@var{window}inthecyclicorderingofwindows.Theotherargumentsspecifywhichwindowstoincludeinthecycle,asin@code{next-window}.@enddefun@deffnCommandother-windowcountThisfunctionselectsthe@var{count}thfollowingwindowinthecyclicorder.Ifcountisnegative,thenitselectsthe@minus{}@var{count}thprecedingwindow.Itreturns@code{nil}.Inaninteractivecall,@var{count}isthenumericprefixargument.@enddeffn@cEmacs19feature@defunwalk-windowsproc&optionalminibufall-framesThisfunctioncyclesthroughallwindows,calling@code{proc}onceforeachwindowwiththewindowasitssoleargument.Theoptionalarguments@var{minibuf}and@var{all-frames}specifythesetofwindowstoincludeinthescan.See@code{next-window},above,fordetails.@enddefun@nodeBuffersandWindows@sectionBuffersandWindows@cindexexaminingwindows@cindexwindows,controllingprecisely@cindexbuffers,controlledinwindowsThissectiondescribeslow-levelfunctionstoexaminewindowsortodisplaybuffersinwindowsinapreciselycontrolledfashion.@iftexSeethefollowingsectionfor@endiftex@ifinfo@xref{DisplayingBuffers},for@endifinforelatedfunctionsthatfindawindowtouseandspecifyabufferforit.Thefunctionsdescribedthereareeasiertousethanthese,buttheyemployheuristicsinchoosingorcreatingawindow;usethesefunctionswhenyouneedcompletecontrol.@defunset-window-bufferwindowbuffer-or-nameThisfunctionmakes@var{window}display@var{buffer-or-name}asitscontents.Itreturns@code{nil}.@example@group(set-window-buffer(selected-window)"foo")@result{}nil@endgroup@endexample@enddefun@defunwindow-buffer&optionalwindowThisfunctionreturnsthebufferthat@var{window}isdisplaying.If@var{window}isomitted,thisfunctionreturnsthebufferfortheselectedwindow.@example@group(window-buffer)@result{}#<bufferwindows.texi>@endgroup@endexample@enddefun@defunget-buffer-windowbuffer-or-name&optionalall-framesThisfunctionreturnsawindowcurrentlydisplaying@var{buffer-or-name},or@code{nil}ifthereisnone.Ifthereareseveralsuchwindows,thenthefunctionreturnsthefirstoneinthecyclicorderingofwindows,startingfromtheselectedwindow.@xref{CyclicWindowOrdering}.Theargument@var{all-frames}controlswhichwindowstoconsider.@itemize@bullet@itemIfitis@code{nil},considerwindowsontheselectedframe.@itemIfitis@code{t},considerwindowsonallframes.@itemIfitis@code{visible},considerwindowsonallvisibleframes.@itemIfitis0,considerwindowsonallvisibleoriconifiedframes.@itemIfitisaframe,considerwindowsonthatframe.@enditemize@enddefun@nodeDisplayingBuffers@sectionDisplayingBuffersinWindows@cindexswitchingtoabuffer@cindexdisplayingabufferInthissectionwedescribeconvenientfunctionsthatchooseawindowautomaticallyanduseittodisplayaspecifiedbuffer.Thesefunctionscanalsosplitanexistingwindowincertaincircumstances.Wealsodescribevariablesthatparameterizetheheuristicsusedforchoosingawindow.@iftexSeetheprecedingsectionfor@endiftex@ifinfo@xref{BuffersandWindows},for@endifinfolow-levelfunctionsthatgiveyoumoreprecisecontrol.DonotusethefunctionsinthissectioninordertomakeabuffercurrentsothataLispprogramcanaccessormodifyit;theyaretoodrasticforthatpurpose,sincetheychangethedisplayofbuffersinwindows,whichisgratuitousandwillsurprisetheuser.Instead,use@code{set-buffer}(@pxref{CurrentBuffer})and@code{save-excursion}(@pxref{Excursions}),whichdesignatebuffersascurrentforprogrammedaccesswithoutaffectingthedisplayofbuffersinwindows.@deffnCommandswitch-to-bufferbuffer-or-name&optionalnorecordThisfunctionmakes@var{buffer-or-name}thecurrentbuffer,andalsodisplaysthebufferintheselectedwindow.Thismeansthatahumancanseethebufferandsubsequentkeyboardcommandswillapplytoit.Contrastthiswith@code{set-buffer},whichmakes@var{buffer-or-name}thecurrentbufferbutdoesnotdisplayitintheselectedwindow.@xref{CurrentBuffer}.If@var{buffer-or-name}doesnotidentifyanexistingbuffer,thenanewbufferbythatnameiscreated.Themajormodeforthenewbufferissetaccordingtothevariable@code{default-major-mode}.@xref{AutoMajorMode}.Normallythespecifiedbufferisputatthefrontofthebufferlist.Thisaffectstheoperationof@code{other-buffer}.However,if@var{norecord}isnon-@code{nil},thisisnotdone.@xref{TheBufferList}.The@code{switch-to-buffer}functionisoftenusedinteractively,asthebindingof@kbd{C-xb}.Itisalsousedfrequentlyinprograms.Italwaysreturns@code{nil}.@enddeffn@deffnCommandswitch-to-buffer-other-windowbuffer-or-nameThisfunctionmakes@var{buffer-or-name}thecurrentbufferanddisplaysitinawindownotcurrentlyselected.Itthenselectsthatwindow.Thehandlingofthebufferisthesameasin@code{switch-to-buffer}.Thecurrentlyselectedwindowisabsolutelyneverusedtodothejob.Ifitistheonlywindow,thenitissplittomakeadistinctwindowforthispurpose.Iftheselectedwindowisalreadydisplayingthebuffer,thenitcontinuestodoso,butanotherwindowisnonethelessfoundtodisplayitinaswell.@enddeffn@defunpop-to-bufferbuffer-or-name&optionalother-windowThisfunctionmakes@var{buffer-or-name}thecurrentbufferandswitchestoitinsomewindow,preferablynotthewindowpreviouslyselected.The``popped-to''windowbecomestheselectedwindowwithinitsframe.Ifthevariable@code{pop-up-frames}isnon-@code{nil},@code{pop-to-buffer}looksforawindowinanyvisibleframealreadydisplayingthebuffer;ifthereisone,itreturnsthatwindowandmakesitbeselectedwithinitsframe.Ifthereisnone,itcreatesanewframeanddisplaysthebufferinit.If@code{pop-up-frames}is@code{nil},then@code{pop-to-buffer}operatesentirelywithintheselectedframe.(Iftheselectedframehasjustaminibuffer,@code{pop-to-buffer}operateswithinthemostrecentlyselectedframethatwasnotjustaminibuffer.)Ifthevariable@code{pop-up-windows}isnon-@code{nil},windowsmaybesplittocreateanewwindowthatisdifferentfromtheoriginalwindow.Fordetails,see@ref{ChoosingWindow}.If@var{other-window}isnon-@code{nil},@code{pop-to-buffer}findsorcreatesanotherwindowevenif@var{buffer-or-name}isalreadyvisibleintheselectedwindow.Thus@var{buffer-or-name}couldendupdisplayedintwowindows.Ontheotherhand,if@var{buffer-or-name}isalreadydisplayedintheselectedwindowand@var{other-window}is@code{nil},thentheselectedwindowisconsideredsufficientdisplayfor@var{buffer-or-name},sothatnothingneedstobedone.Allthevariablesthataffect@code{display-buffer}affect@code{pop-to-buffer}aswell.@xref{ChoosingWindow}.If@var{buffer-or-name}isastringthatdoesnotnameanexistingbuffer,abufferbythatnameiscreated.Themajormodeforthenewbufferissetaccordingtothevariable@code{default-major-mode}.@xref{AutoMajorMode}.@enddefun@deffnCommandreplace-buffer-in-windowsbufferThisfunctionreplaces@var{buffer}withsomeotherbufferinallwindowsdisplayingit.Theotherbufferusedischosenwith@code{other-buffer}.Intheusualapplicationsofthisfunction,youdon't care which other buffer is used; you just want to make sure that@var{buffer} is no longer displayed.This function returns @code{nil}.@end deffn@node Choosing Window@section Choosing a Window for Display This section describes the basic facility that chooses a window todisplay a buffer in---@code{display-buffer}. All the higher-levelfunctions and commands use this subroutine. Here we describe how to use@code{display-buffer} and how to customize it.@deffn Command display-buffer buffer-or-name &optional not-this-windowThis command makes @var{buffer-or-name} appear in some window, like@code{pop-to-buffer}, but it does not select that window and does notmake the buffer current. The identity of the selected window isunaltered by this function.If @var{not-this-window} is non-@code{nil}, it means to display thespecified buffer in a window other than the selected one, even if it isalready on display in the selected window. This can cause the buffer toappear in two windows at once. Otherwise, if @var{buffer-or-name} isalready being displayed in any window, that is good enough, so thisfunction does nothing.@code{display-buffer} returns the window chosen to display@var{buffer-or-name}.Precisely how @code{display-buffer} finds or creates a window depends onthe variables described below.@end deffn@defopt pop-up-windowsThis variable controls whether @code{display-buffer} makes new windows.If it is non-@code{nil} and there is only one window, then that windowis split. If it is @code{nil}, then @code{display-buffer} does notsplit the single window, but uses it whole.@end defopt@defopt split-height-thresholdThis variable determines when @code{display-buffer} may split a window,if there are multiple windows. @code{display-buffer} always splits thelargest window if it has at least this many lines. If the largestwindow is not this tall, it is split only if it is the sole window and@code{pop-up-windows} is non-@code{nil}.@end defopt@c Emacs 19 feature@defopt pop-up-framesThis variable controls whether @code{display-buffer} makes new frames.If it is non-@code{nil}, @code{display-buffer} looks for an existingwindow already displaying the desired buffer, on any visible frame. Ifit finds one, it returns that window. Otherwise it makes a new frame.The variables @code{pop-up-windows} and @code{split-height-threshold} donot matter if @code{pop-up-frames} is non-@code{nil}.If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} eithersplits a window or reuses one.@xref{Frames}, for more information.@end defopt@c Emacs 19 feature@defvar pop-up-frame-functionThis variable specifies how to make a new frame if @code{pop-up-frames}is non-@code{nil}.Its value should be a function of no arguments. When@code{display-buffer} makes a new frame, it does so by calling thatfunction, which should return a frame. The default value of thevariable is a function that creates a frame using parameters from@code{pop-up-frame-alist}.@end defvar@defvar pop-up-frame-alistThis variable holds an alist specifying frame parameters used when@code{display-buffer} makes a new frame. @xref{Frame Parameters}, formore information about frame parameters.@end defvar@defvar special-display-buffer-namesA list of buffer names for buffers that should be displayed specially.If the buffer'snameisinthislist,@code{display-buffer}handlesthebufferspecially.Bydefault,specialdisplaymeanstogivethebufferadedicatedframe.Ifanelementisalist,insteadofastring,thenthe@sc{car}ofthelististhebuffername,andtherestofthelistsayshowtocreatetheframe.Therearetwopossibilitiesfortherestofthelist.Itcanbeanalist,specifyingframeparameters,oritcancontainafunctionandargumentstogivetoit.(Thefunction's first argument is always thebuffer to be displayed; the arguments from the list come after that.)@end defvar@defvar special-display-regexpsA list of regular expressions that specify buffers that should bedisplayed specially. If the buffer'snamematchesanyoftheregularexpressionsinthislist,@code{display-buffer}handlesthebufferspecially.Bydefault,specialdisplaymeanstogivethebufferadedicatedframe.Ifanelementisalist,insteadofastring,thenthe@sc{car}ofthelististheregularexpression,andtherestofthelistsayshowtocreatetheframe.Seeabove,under@code{special-display-buffer-names}.@enddefvar@defvarspecial-display-functionThisvariableholdsthefunctiontocalltodisplayabufferspecially.Itreceivesthebufferasanargument,andshouldreturnthewindowinwhichitisdisplayed.Thedefaultvalueofthisvariableis@code{special-display-popup-frame}.@enddefvar@defunspecial-display-popup-framebufferThisfunctionmakes@var{buffer}visibleinaframeofitsown.If@var{buffer}isalreadydisplayedinawindowinsomeframe,itmakestheframevisibleandraisesit,tousethatwindow.Otherwise,itcreatesaframethatwillbededicatedto@var{buffer}.Thisfunctionusesanexistingwindowdisplaying@var{buffer}whetherornotitisinaframeofitsown;butifyousetuptheabovevariablesinyourinitfile,before@var{buffer}wascreated,thenpresumablythewindowwaspreviouslymadebythisfunction.@enddefun@defoptspecial-display-frame-alistThisvariableholdsframeparametersfor@code{special-display-popup-frame}tousewhenitcreatesaframe.@enddefopt@defoptsame-window-buffer-namesAlistofbuffernamesforbuffersthatshouldbedisplayedintheselectedwindow.Ifthebuffer's name is in this list,@code{display-buffer} handles the buffer by switching to it in theselected window.@end defopt@defopt same-window-regexpsA list of regular expressions that specify buffers that should bedisplayed in the selected window. If the buffer'snamematchesanyoftheregularexpressionsinthislist,@code{display-buffer}handlesthebufferbyswitchingtoitintheselectedwindow.@enddefopt@cEmacs19feature@defvardisplay-buffer-functionThisvariableisthemostflexiblewaytocustomizethebehaviorof@code{display-buffer}.Ifitisnon-@code{nil},itshouldbeafunctionthat@code{display-buffer}callstodothework.Thefunctionshouldaccepttwoarguments,thesametwoargumentsthat@code{display-buffer}received.Itshouldchooseorcreateawindow,displaythespecifiedbuffer,andthenreturnthewindow.Thishooktakesprecedenceoveralltheotheroptionsandhooksdescribedabove.@enddefvar@cEmacs19feature@cindexdedicatedwindowAwindowcanbemarkedas``dedicated''toitsbuffer.Then@code{display-buffer}doesnottrytousethatwindow.@defunwindow-dedicated-pwindowThisfunctionreturns@code{t}if@var{window}ismarkedasdedicated;otherwise@code{nil}.@enddefun@defunset-window-dedicated-pwindowflagThisfunctionmarks@var{window}asdedicatedif@var{flag}isnon-@code{nil},andnondedicatedotherwise.@enddefun@nodeWindowPoint@sectionWindowsandPoint@cindexwindowposition@cindexwindowpoint@cindexpositioninwindow@cindexpointinwindowEachwindowhasitsownvalueofpoint,independentofthevalueofpointinotherwindowsdisplayingthesamebuffer.Thismakesitusefultohavemultiplewindowsshowingonebuffer.@itemize@bullet@itemThewindowpointisestablishedwhenawindowisfirstcreated;itisinitializedfromthebuffer's point, or from the window point of anotherwindow opened on the buffer if such a window exists.@itemSelecting a window sets the value of point in its buffer to the window'svalueofpoint.Conversely,deselectingawindowsetsthewindow'svalue of point from that of the buffer. Thus, when you switch betweenwindows that display a given buffer, the point value for the selectedwindow is in effect in the buffer, while the point values for the otherwindows are stored in those windows.@itemAs long as the selected window displays the current buffer, the window'spointandthebuffer's point always move together; they remain equal.@item@xref{Positions}, for more details on buffer positions.@end itemize As far as the user is concerned, point is where the cursor is, andwhen the user switches to another buffer, the cursor jumps to theposition of point in that buffer.@defun window-point windowThis function returns the current position of point in @var{window}.For a nonselected window, this is the value point would have (in thatwindow'sbuffer)ifthatwindowwereselected.When@var{window}istheselectedwindowanditsbufferisalsothecurrentbuffer,thevaluereturnedisthesameaspointinthatbuffer.Strictlyspeaking,itwouldbemorecorrecttoreturnthe``top-level''valueofpoint,outsideofany@code{save-excursion}forms.Butthatvalueishardtofind.@enddefun@defunset-window-pointwindowpositionThisfunctionpositionspointin@var{window}atposition@var{position}in@var{window}'s buffer.@end defun@node Window Start@section The Window Start Position Each window contains a marker used to keep track of a buffer positionthat specifies where in the buffer display should start. This positionis called the @dfn{display-start} position of the window (or just the@dfn{start}). The character after this position is the one that appearsat the upper left corner of the window. It is usually, but notinevitably, at the beginning of a text line.@defun window-start &optional window@cindex window top lineThis function returns the display-start position of window@var{window}. If @var{window} is @code{nil}, the selected window isused. For example, @example@group(window-start) @result{} 7058@end group@end exampleWhen you create a window, or display a different buffer in it, thedisplay-start position is set to a display-start position recently usedfor the same buffer, or 1 if the buffer doesn'thaveany.Redisplayupdatesthewindow-startposition(ifyouhavenotspecifieditexplicitlysincethepreviousredisplay)sothatpointappearsonthescreen.Nothingexceptredisplayautomaticallychangesthewindow-startposition;ifyoumovepoint,donotexpectthewindow-startpositiontochangeinresponseuntilafterthenextredisplay.Forarealisticexampleofusing@code{window-start},seethedescriptionof@code{count-lines}in@ref{TextLines}.@enddefun@defunwindow-end&optionalwindowThisfunctionreturnsthepositionoftheendofthedisplayinwindow@var{window}.If@var{window}is@code{nil},theselectedwindowisused.Simplychangingthebuffertextormovingpointdoesnotupdatethevaluethat@code{window-end}returns.ThevalueisupdatedonlywhenEmacsredisplaysandredisplayactuallyfinishes.Ifthelastredisplayof@var{window}waspreempted,anddidnotfinish,Emacsdoesnotknowthepositionoftheendofdisplayinthatwindow.Inthatcase,thisfunctionreturnsavaluethatisnotcorrect.Inafutureversion,@code{window-end}willreturn@code{nil}inthatcase.@ignoreinthatcase,thisfunctionreturns@code{nil}.Youcancomputewheretheendofthewindow@emph{would}havebeen,ifredisplayhadfinished,likethis:@example(save-excursion(goto-char(window-startwindow))(vertical-motion(1-(window-heightwindow))window)(point))@endexample@endignore@enddefun@defunset-window-startwindowposition&optionalnoforceThisfunctionsetsthedisplay-startpositionof@var{window}to@var{position}in@var{window}'s buffer. It returns @var{position}.The display routines insist that the position of point be visible when abuffer is displayed. Normally, they change the display-start position(that is, scroll the window) whenever necessary to make point visible.However, if you specify the start position with this function using@code{nil} for @var{noforce}, it means you want display to start at@var{position} even if that would put the location of point off thescreen. If this does place point off screen, the display routines movepoint to the left margin on the middle line in the window.For example, if point @w{is 1} and you set the start of the window @w{to2}, then point would be ``above'' the top of the window. The displayroutines will automatically move point if it is still 1 when redisplayoccurs. Here is an example:@example@group;; @r{Here is what @samp{foo} looks like before executing};; @r{the @code{set-window-start} expression.}@end group@group---------- Buffer: foo ----------@point{}This is the contents of buffer foo.23456---------- Buffer: foo ----------@end group@group(set-window-start (selected-window) (1+ (window-start)))@result{} 2@end group@group;; @r{Here is what @samp{foo} looks like after executing};; @r{the @code{set-window-start} expression.}---------- Buffer: foo ----------his is the contents of buffer foo.23@point{}456---------- Buffer: foo ----------@end group@end exampleIf @var{noforce} is non-@code{nil}, and @var{position} would place pointoff screen at the next redisplay, then redisplay computes a new window-startposition that works well with point, and thus @var{position} is not used.@end defun@defun pos-visible-in-window-p &optional position windowThis function returns @code{t} if @var{position} is within the rangeof text currently visible on the screen in @var{window}. It returns@code{nil} if @var{position} is scrolled vertically out of view. Theargument @var{position} defaults to the current position of point;@var{window}, to the selected window. Here is an example:@example@group(or (pos-visible-in-window-p (point) (selected-window)) (recenter 0))@end group@end exampleThe @code{pos-visible-in-window-p} function considers only verticalscrolling. If @var{position} is out of view only because @var{window}has been scrolled horizontally, @code{pos-visible-in-window-p} returns@code{t}. @xref{Horizontal Scrolling}.@end defun@node Vertical Scrolling@section Vertical Scrolling@cindex vertical scrolling@cindex scrolling vertically Vertical scrolling means moving the text up or down in a window. Itworks by changing the value of the window'sdisplay-startlocation.Itmayalsochangethevalueof@code{window-point}tokeepitonthescreen.Inthecommands@code{scroll-up}and@code{scroll-down},thedirections``up''and``down''refertothemotionofthetextinthebufferatwhichyouarelookingthroughthewindow.Imaginethatthetextiswrittenonalongrollofpaperandthatthescrollingcommandsmovethepaperupanddown.Thus,ifyouarelookingattextinthemiddleofabufferandrepeatedlycall@code{scroll-down},youwilleventuallyseethebeginningofthebuffer.Somepeoplehaveurgedthattheoppositeconventionbeused:theyimaginethatthewindowmovesovertextthatremainsinplace.Then``down''commandswouldtakeyoutotheendofthebuffer.Thisviewismoreconsistentwiththeactualrelationshipbetweenwindowsandthetextinthebuffer,butitislesslikewhattheusersees.Thepositionofawindowontheterminaldoesnotmove,andshortscrollingcommandsclearlymovethetextupordownonthescreen.Wehavechosennamesthatfittheuser's point of view. The scrolling functions (aside from @code{scroll-other-window}) haveunpredictable results if the current buffer is different from the bufferthat is displayed in the selected window. @xref{Current Buffer}.@deffn Command scroll-up &optional countThis function scrolls the text in the selected window upward@var{count} lines. If @var{count} is negative, scrolling is actuallydownward.If @var{count} is @code{nil} (or omitted), then the length of scrollis @code{next-screen-context-lines} lines less than the usable height ofthe window (not counting its mode line).@code{scroll-up} returns @code{nil}.@end deffn@deffn Command scroll-down &optional countThis function scrolls the text in the selected window downward@var{count} lines. If @var{count} is negative, scrolling is actuallyupward.If @var{count} is omitted or @code{nil}, then the length of the scrollis @code{next-screen-context-lines} lines less than the usable height ofthe window (not counting its mode line).@code{scroll-down} returns @code{nil}.@end deffn@deffn Command scroll-other-window &optional countThis function scrolls the text in another window upward @var{count}lines. Negative values of @var{count}, or @code{nil}, are handledas in @code{scroll-up}.You can specify a buffer to scroll with the variable@code{other-window-scroll-buffer}. When the selected window is theminibuffer, the next window is normally the one at the top left corner.You can specify a different window to scroll with the variable@code{minibuffer-scroll-window}. This variable has no effect when anyother window is selected. @xref{Minibuffer Misc}.When the minibuffer is active, it is the next window if the selectedwindow is the one at the bottom right corner. In this case,@code{scroll-other-window} attempts to scroll the minibuffer. If theminibuffer contains just one line, it has nowhere to scroll to, so theline reappears after the echo area momentarily displays the message``Beginning of buffer''.@end deffn@c Emacs 19 feature@defvar other-window-scroll-bufferIf this variable is non-@code{nil}, it tells @code{scroll-other-window}which buffer to scroll.@end defvar@defopt scroll-stepThis variable controls how scrolling is done automatically when pointmoves off the screen. If the value is zero, then redisplay scrolls thetext to center point vertically in the window. If the value is apositive integer @var{n}, then redisplay brings point back on screen byscrolling @var{n} lines in either direction, if possible; otherwise, itcenters point. The default value is zero.@end defopt@defopt next-screen-context-linesThe value of this variable is the number of lines of continuity toretain when scrolling by full screens. For example, @code{scroll-up}with an argument of @code{nil} scrolls so that this many lines at thebottom of the window appear instead at the top. The default value is@code{2}.@end defopt@deffn Command recenter &optional count@cindex centering pointThis function scrolls the selected window to put the text where pointis located at a specified vertical position within the window.If @var{count} is a nonnegative number, it puts the line containingpoint @var{count} lines down from the top of the window. If @var{count}is a negative number, then it counts upward from the bottom of thewindow, so that @minus{}1 stands for the last usable line in the window.If @var{count} is a non-@code{nil} list, then it stands for the line inthe middle of the window.If @var{count} is @code{nil}, @code{recenter} puts the line containingpoint in the middle of the window, then clears and redisplays the entireselected frame.When @code{recenter} is called interactively, @var{count} is the rawprefix argument. Thus, typing @kbd{C-u} as the prefix sets the@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets@var{count} to 4, which positions the current line four lines from thetop.With an argument of zero, @code{recenter} positions the current line atthe top of the window. This action is so handy that some people make aseparate key binding to do this. For example,@example@group(defun line-to-top-of-window () "Scroll current line to top of window.Replaces three keystroke sequence C-u 0 C-l." (interactive) (recenter 0))(global-set-key [kp-multiply] 'line-to-top-of-window)@endgroup@endexample@enddeffn@nodeHorizontalScrolling@sectionHorizontalScrolling@cindexhorizontalscrollingBecausewereadEnglishfirstfromtoptobottomandsecondfromlefttoright,horizontalscrollingisnotlikeverticalscrolling.Verticalscrollinginvolvesselectionofacontiguousportionoftexttodisplay.Horizontalscrollingcausespartofeachlinetogooffscreen.Theamountofhorizontalscrollingisthereforespecifiedasanumberofcolumnsratherthanasapositioninthebuffer.Ithasnothingtodowiththedisplay-startpositionreturnedby@code{window-start}.Usually,nohorizontalscrollingisineffect;thentheleftmostcolumnisattheleftedgeofthewindow.Inthisstate,scrollingtotherightismeaningless,sincethereisnodatatotheleftofthescreentoberevealedbyit;sothisisnotallowed.Scrollingtotheleftisallowed;itscrollsthefirstcolumnsoftextofftheedgeofthewindowandcanrevealadditionalcolumnsontherightthatweretruncatedbefore.Onceawindowhasanonzeroamountofleftwardhorizontalscrolling,youcanscrollitbacktotheright,butonlysofarastoreducethenethorizontalscrolltozero.Thereisnolimittohowfarleftyoucanscroll,buteventuallyallthetextwilldisappearofftheleftedge.@deffnCommandscroll-leftcountThisfunctionscrollstheselectedwindow@var{count}columnstotheleft(ortotherightif@var{count}isnegative).Thereturnvalueisthetotalamountofleftwardhorizontalscrollingineffectafterthechange---justlikethevaluereturnedby@code{window-hscroll}(below).@enddeffn@deffnCommandscroll-rightcountThisfunctionscrollstheselectedwindow@var{count}columnstotheright(ortotheleftif@var{count}isnegative).Thereturnvalueisthetotalamountofleftwardhorizontalscrollingineffectafterthechange---justlikethevaluereturnedby@code{window-hscroll}(below).Onceyouscrollawindowasfarrightasitcango,backtoitsnormalpositionwherethetotalleftwardscrollingiszero,attemptstoscrollanyfartherrighthavenoeffect.@enddeffn@defunwindow-hscroll&optionalwindowThisfunctionreturnsthetotalleftwardhorizontalscrollingof@var{window}---thenumberofcolumnsbywhichthetextin@var{window}isscrolledleftpasttheleftmargin.Thevalueisnevernegative.Itiszerowhennohorizontalscrollinghasbeendonein@var{window}(whichisusuallythecase).If@var{window}is@code{nil},theselectedwindowisused.@example@group(window-hscroll)@result{}0@endgroup@group(scroll-left5)@result{}5@endgroup@group(window-hscroll)@result{}5@endgroup@endexample@enddefun@defunset-window-hscrollwindowcolumnsThisfunctionsetsthenumberofcolumnsfromtheleftmarginthat@var{window}isscrolledtothevalueof@var{columns}.Theargument@var{columns}shouldbezeroorpositive;ifnot,itistakenaszero.Thevaluereturnedis@var{columns}.@example@group(set-window-hscroll(selected-window)10)@result{}10@endgroup@endexample@enddefunHereishowyoucandeterminewhetheragivenposition@var{position}isoffthescreenduetohorizontalscrolling:@example@group(defunhscroll-on-screen(windowposition)(save-excursion(goto-charposition)(and(>=(-(current-column)(window-hscrollwindow))0)(<(-(current-column)(window-hscrollwindow))(window-widthwindow)))))@endgroup@endexample@nodeSizeofWindow@sectionTheSizeofaWindow@cindexwindowsize@cindexsizeofwindowAnEmacswindowisrectangular,anditssizeinformationconsistsoftheheight(thenumberoflines)andthewidth(thenumberofcharacterpositionsineachline).Themodelineisincludedintheheight.Butthewidthdoesnotcountthescrollbarorthecolumnof@samp{|}charactersthatseparatesside-by-sidewindows.Thefollowingthreefunctionsreturnsizeinformationaboutawindow:@defunwindow-height&optionalwindowThisfunctionreturnsthenumberoflinesin@var{window},includingitsmodeline.If@var{window}fillsitsentireframe,thisisonelessthanthevalueof@code{frame-height}onthatframe(sincethelastlineisalwaysreservedfortheminibuffer).If@var{window}is@code{nil},thefunctionusestheselectedwindow.@example@group(window-height)@result{}23@endgroup@group(split-window-vertically)@result{}#<window4onwindows.texi>@endgroup@group(window-height)@result{}11@endgroup@endexample@enddefun@defunwindow-width&optionalwindowThisfunctionreturnsthenumberofcolumnsin@var{window}.If@var{window}fillsitsentireframe,thisisthesameasthevalueof@code{frame-width}onthatframe.Thewidthdoesnotincludethewindow's scroll bar or the column of @samp{|} characters that separatesside-by-side windows.If @var{window} is @code{nil}, the function uses the selected window.@example@group(window-width) @result{} 80@end group@end example@end defun@defun window-edges &optional windowThis function returns a list of the edge coordinates of @var{window}.If @var{window} is @code{nil}, the selected window is used.The order of the list is @code{(@var{left} @var{top} @var{right}@var{bottom})}, all elements relative to 0, 0 at the top left corner ofthe frame. The element @var{right} of the value is one more than therightmost column used by @var{window}, and @var{bottom} is one more thanthe bottommost row used by @var{window} and its mode-line.When you have side-by-side windows, the right edge value for a windowwith a neighbor on the right includes the width of the separator betweenthe window and that neighbor. This separator may be a column of@samp{|} characters or it may be a scroll bar. Since the width of thewindow does not include this separator, the width does not equal thedifference between the right and left edges in this case.Here is the result obtained on a typical 24-line terminal with just onewindow:@example@group(window-edges (selected-window)) @result{} (0 0 80 23)@end group@end example@noindentThe bottom edge is at line 23 because the last line is the echo area.If @var{window} is at the upper left corner of its frame, then@var{bottom} is the same as the value of @code{(window-height)},@var{right} is almost the same as the value of@code{(window-width)}@footnote{They are not exactly equal because@var{right} includes the vertical separator line or scroll bar, while@code{(window-width)} does not.}, and @var{top} and @var{left} are zero.For example, the edges of the following window are @w{@samp{0 0 5 8}}.Assuming that the frame has more than 8 columns, the last column of thewindow (column 7) holds a border rather than text. The last row (row 4)holds the mode line, shown here with @samp{xxxxxxxxx}.@example@group 0 _______ 0 | | | | | | | | xxxxxxxxx 4 7 @end group@end exampleWhen there are side-by-side windows, any window not at the right edge ofits frame has a separator in its last column or columns. The separatorcounts as one or two columns in the width of the window. A window neverincludes a separator on its left, since that belongs to the window tothe left.In the following example, let'ssupposethattheframeis7columnswide.Thentheedgesoftheleftwindoware@w{@samp{0043}}andtheedgesoftherightwindoware@w{@samp{4073}}.@example@group______||||||xxxxxxxxx0347@endgroup@endexample@enddefun@nodeResizingWindows@sectionChangingtheSizeofaWindow@cindexwindowresizing@cindexchangingwindowsize@cindexwindowsize,changingThewindowsizefunctionsfallintotwoclasses:high-levelcommandsthatchangethesizeofwindowsandlow-levelfunctionsthataccesswindowsize.Emacsdoesnotpermitoverlappingwindowsorgapsbetweenwindows,soresizingonewindowaffectsotherwindows.@deffnCommandenlarge-windowsize&optionalhorizontalThisfunctionmakestheselectedwindow@var{size}linestaller,stealinglinesfromneighboringwindows.Ittakesthelinesfromonewindowatatimeuntilthatwindowisusedup,thentakesfromanother.Ifawindowfromwhichlinesarestolenshrinksbelow@code{window-min-height}lines,thatwindowdisappears.If@var{horizontal}isnon-@code{nil},thisfunctionmakes@var{window}widerby@var{size}columns,stealingcolumnsinsteadoflines.Ifawindowfromwhichcolumnsarestolenshrinksbelow@code{window-min-width}columns,thatwindowdisappears.Iftherequestedsizewouldexceedthatofthewindow's frame, then thefunction makes the window occupy the entire height (or width) of theframe.If @var{size} is negative, this function shrinks the window by@minus{}@var{size} lines or columns. If that makes the window smallerthan the minimum size (@code{window-min-height} and@code{window-min-width}), @code{enlarge-window} deletes the window.@code{enlarge-window} returns @code{nil}. @end deffn@deffn Command enlarge-window-horizontally columnsThis function makes the selected window @var{columns} wider.It could be defined as follows:@example@group(defun enlarge-window-horizontally (columns) (enlarge-window columns t))@end group@end example@end deffn@deffn Command shrink-window size &optional horizontalThis function is like @code{enlarge-window} but negates the argument@var{size}, making the selected window smaller by giving lines (orcolumns) to the other windows. If the window shrinks below@code{window-min-height} or @code{window-min-width}, then it disappears.If @var{size} is negative, the window is enlarged by @minus{}@var{size}lines or columns.@end deffn@deffn Command shrink-window-horizontally columnsThis function makes the selected window @var{columns} narrower.It could be defined as follows:@example@group(defun shrink-window-horizontally (columns) (shrink-window columns t))@end group@end example@end deffn@cindex minimum window size The following two variables constrain the window-size-changingfunctions to a minimum height and width.@defopt window-min-heightThe value of this variable determines how short a window may becomebefore it is automatically deleted. Making a window smaller than@code{window-min-height} automatically deletes it, and no window may becreated shorter than this. The absolute minimum height is two (allowingone line for the mode line, and one line for the buffer display).Actions that change window sizes reset this variable to two if it isless than two. The default value is 4.@end defopt@defopt window-min-widthThe value of this variable determines how narrow a window may becomebefore it automatically deleted. Making a window smaller than@code{window-min-width} automatically deletes it, and no window may becreated narrower than this. The absolute minimum width is one; anyvalue below that is ignored. The default value is 10.@end defopt@defvar window-size-change-functionsThis variable holds a list of functions to be called if the size of anywindow changes for any reason. The functions are called just once perredisplay, and just once for each frame on which size changes haveoccurred.Each function receives the frame as its sole argument. There is nodirect way to find out which windows changed size, or precisely how;however, if your size-change function keeps track, after each change, ofthe windows that interest you, you can figure out what has changed bycomparing the old size data with the new.Creating or deleting windows counts as a size change, and thereforecauses these functions to be called. Changing the frame size alsocounts, because it changes the sizes of the existing windows.It is not a good idea to use @code{save-window-excursion} in thesefunctions, because that always counts as a size change, and it wouldcause these functions to be called over and over. In most cases,@code{save-selected-window} is what you need here.@end defvar@node Coordinates and Windows@section Coordinates and WindowsThis section describes how to relate screen coordinates to windows.@defun window-at x y &optional frameThis function returns the window containing the specified cursorposition in the frame @var{frame}. The coordinates @var{x} and @var{y}are measured in characters and count from the top left corner of theframe. If they are out of range, @code{window-at} returns @code{nil}.If you omit @var{frame}, the selected frame is used.@end defun@defun coordinates-in-window-p coordinates windowThis function checks whether a particular frame position falls withinthe window @var{window}.@need 3000The argument @var{coordinates} is a cons cell of this form:@example(@var{x} . @var{y})@end example@noindentThe coordinates @var{x} and @var{y} are measured in characters, andcount from the top left corner of the screen or frame.The value of @code{coordinates-in-window-p} is non-@code{nil} if thecoordinates are inside @var{window}. The value also indicates what partof the window the position is in, as follows:@table @code@item (@var{relx} . @var{rely})The coordinates are inside @var{window}. The numbers @var{relx} and@var{rely} are the equivalent window-relative coordinates for thespecified position, counting from 0 at the top left corner of thewindow.@item mode-lineThe coordinates are in the mode line of @var{window}.@item vertical-splitThe coordinates are in the vertical line between @var{window} and itsneighbor to the right. This value occurs only if the window doesn'thaveascrollbar;positionsinascrollbarareconsideredoutsidethewindow.@itemnilThecoordinatesarenotinanypartof@var{window}.@endtableThefunction@code{coordinates-in-window-p}doesnotrequireaframeasargumentbecauseitalwaysusestheframethat@var{window}ison.@enddefun@nodeWindowConfigurations@sectionWindowConfigurations@cindexwindowconfigurations@cindexsavingwindowinformationA@dfn{windowconfiguration}recordstheentirelayoutofaframe---allwindows,theirsizes,whichbufferstheycontain,whatpartofeachbufferisdisplayed,andthevaluesofpointandthemark.Youcanbringbackanentirepreviouslayoutbyrestoringawindowconfigurationpreviouslysaved.Ifyouwanttorecordallframesinsteadofjustone,useaframeconfigurationinsteadofawindowconfiguration.@xref{FrameConfigurations}.@defuncurrent-window-configurationThisfunctionreturnsanewobjectrepresentingEmacs's current windowconfiguration, namely the number of windows, their sizes and currentbuffers, which window is the selected window, and for each window thedisplayed buffer, the display-start position, and the positions of pointand the mark. An exception is made for point in the current buffer,whose value is not saved.@end defun@defun set-window-configuration configurationThis function restores the configuration of Emacs'swindowsandbufferstothestatespecifiedby@var{configuration}.Theargument@var{configuration}mustbeavaluethatwaspreviouslyreturnedby@code{current-window-configuration}.Thisfunctionalwayscountsasawindowsizechangeandtriggersexecutionofthe@code{window-size-change-functions}.(Itdoesn't knowhow to tell whether the new configuration actually differs from the oldone.)Here is a way of using this function to get the same effectas @code{save-window-excursion}:@example@group(let ((config (current-window-configuration))) (unwind-protect (progn (split-window-vertically nil) @dots{}) (set-window-configuration config)))@end group@end example@end defun@defspec save-window-excursion forms@dots{}This special form records the window configuration, executes @var{forms}in sequence, then restores the earlier window configuration. The windowconfiguration includes the value of point and the portion of the bufferthat is visible. It also includes the choice of selected window.However, it does not include the value of point in the current buffer;use @code{save-excursion} if you wish to preserve that.Don'tusethisconstructwhen@code{save-selected-window}isallyouneed.Exitfrom@code{save-window-excursion}alwaystriggersexecutionofthe@code{window-size-change-functions}.(Itdoesn't know how to tellwhether the restored configuration actually differs from the one ineffect at the end of the @var{forms}.)The return value is the value of the final form in @var{forms}.For example:@example@group(split-window) @result{} #<window 25 on control.texi>@end group@group(setq w (selected-window)) @result{} #<window 19 on control.texi>@end group@group(save-window-excursion (delete-other-windows w) (switch-to-buffer "foo") 'do-something)@result{}do-something;;@r{Thescreenisnowsplitagain.}@endgroup@endexample@enddefspec@defunwindow-configuration-pobjectThisfunctionreturns@code{t}if@var{object}isawindowconfiguration.@enddefunPrimitivestolookinsideofwindowconfigurationswouldmakesense,butnoneareimplemented.Itisnotcleartheyareusefulenoughtobeworthimplementing.