@@ -987,6 +987,85 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
987987 return buf -> b_fnum ;
988988}
989989
990+ /// Open a new window.
991+ ///
992+ /// Currently this is used to open floating and external windows.
993+ /// Floats are windows that are drawn above the split layout, at some anchor
994+ /// position in some other window. Floats can be draw internally or by external
995+ /// GUI with the |ui-multigrid| extension. External windows are only supported
996+ /// with multigrid GUIs, and are displayed as separate top-level windows.
997+ ///
998+ /// Exactly one of `external` and `relative` must be specified.
999+ ///
1000+ /// @param buffer handle of buffer to be displayed in the window
1001+ /// @param enter whether the window should be entered (made the current window)
1002+ /// @param width width of window (in character cells)
1003+ /// @param height height of window (in character cells)
1004+ /// @param options dict of options for configuring window positioning
1005+ /// accepts the following keys:
1006+ /// `relative`: If set, the window becomes a floating window. The window
1007+ /// will be placed with row,col coordinates relative one of the
1008+ /// following:
1009+ /// "editor" the global editor grid
1010+ /// "win" a window. Use 'win' option below to specify window id,
1011+ /// or current window will be used by default.
1012+ /// "cursor" the cursor position in current window.
1013+ /// `anchor`: the corner of the float that the row,col position defines
1014+ /// "NW" north-west (default)
1015+ /// "NE" north-east
1016+ /// "SW" south-west
1017+ /// "SE" south-east
1018+ /// `focusable`: Whether window can be focused by wincmds and
1019+ /// mouse events. Defaults to true. Even if set to false, the window
1020+ /// can still be entered using |nvim_set_current_win()| API call.
1021+ /// `row`: row position. Screen cell height are used as unit. Can be
1022+ /// floating point.
1023+ /// `col`: column position. Screen cell width is used as unit. Can be
1024+ /// floating point.
1025+ /// `win`: when using relative='win', window id of the window where the
1026+ /// position is defined.
1027+ /// `external` GUI should display the window as an external
1028+ /// top-level window. Currently accepts no other positioning options
1029+ /// together with this.
1030+ ///
1031+ /// With editor positioning row=0, col=0 refers to the top-left corner of the
1032+ /// screen-grid and row=Lines-1, Columns-1 refers to the bottom-right corner.
1033+ /// Floating point values are allowed, but the builtin implementation (used by
1034+ /// TUI and GUIs without multigrid support) will always round down to nearest
1035+ /// integer.
1036+ ///
1037+ /// The behavior of out-of-bounds values, and other configurations that make
1038+ /// the float not fit inside the main editor, is not specified. The builtin
1039+ /// implementation will truncate values so floats are completely
1040+ /// within the main screen grid. External GUIs could let floats hover slightly
1041+ /// outside of the main window, like a tooltip, but this should not be used to
1042+ /// specify arbitrary WM screen positions.
1043+ ///
1044+ /// @param[out] err Error details, if any
1045+ /// @return the buffer handle or 0 when error
1046+ Window nvim_open_win (Buffer buffer , Boolean enter ,
1047+ Integer width , Integer height ,
1048+ Dictionary options , Error * err )
1049+ FUNC_API_SINCE (6 )
1050+ {
1051+ win_T * old = curwin ;
1052+ FloatConfig config = FLOAT_CONFIG_INIT ;
1053+ if (!parse_float_config (options , & config , false, err )) {
1054+ return 0 ;
1055+ }
1056+ win_T * wp = win_new_float (NULL , (int )width , (int )height , config , err );
1057+ if (!wp ) {
1058+ return 0 ;
1059+ }
1060+ if (buffer > 0 ) {
1061+ nvim_set_current_buf (buffer , err );
1062+ }
1063+ if (!enter ) {
1064+ win_enter (old , false);
1065+ }
1066+ return wp -> handle ;
1067+ }
1068+
9901069/// Gets the current list of tabpage handles.
9911070///
9921071/// @return List of tabpage handles
0 commit comments