ruberon/doc/KOSLib.txt

==============================================================================

        Библиотека (KolibriOS)

------------------------------------------------------------------------------
MODULE Out - консольный вывод

        PROCEDURE Open
                формально открывает консольный вывод

        PROCEDURE Int(x, width: INTEGER)
                вывод целого числа x;
                width - количество знакомест, используемых для вывода

        PROCEDURE Real(x: REAL; width: INTEGER)
                вывод вещественного числа x в плавающем формате;
                width - количество знакомест, используемых для вывода

        PROCEDURE Char(x: CHAR)
                вывод символа x

        PROCEDURE FixReal(x: REAL; width, p: INTEGER)
                вывод вещественного числа x в фиксированном формате;
                width - количество знакомест, используемых для вывода;
                p - количество знаков после десятичной точки

        PROCEDURE Ln
                переход на следующую строку

        PROCEDURE String(s: ARRAY OF CHAR)
                вывод строки s

------------------------------------------------------------------------------
MODULE In - консольный ввод

        VAR Done: BOOLEAN
                принимает значение TRUE в случае успешного выполнения
                операции ввода, иначе FALSE

        PROCEDURE Open
                формально открывает консольный ввод,
                также присваивает переменной Done значение TRUE

        PROCEDURE Int(VAR x: INTEGER)
                ввод числа типа INTEGER

        PROCEDURE Char(VAR x: CHAR)
                ввод символа

        PROCEDURE Real(VAR x: REAL)
                ввод числа типа REAL

        PROCEDURE String(VAR s: ARRAY OF CHAR)
                ввод строки

        PROCEDURE Ln
                ожидание нажатия ENTER

------------------------------------------------------------------------------
MODULE Console - дополнительные процедуры консольного вывода

        CONST

        Следующие константы определяют цвет консольного вывода

                Black = 0      Blue = 1           Green = 2
                Cyan = 3       Red = 4            Magenta = 5
                Brown = 6      LightGray = 7      DarkGray = 8
                LightBlue = 9  LightGreen = 10    LightCyan = 11
                LightRed = 12  LightMagenta = 13  Yellow = 14
                White = 15

        PROCEDURE Cls
                очистка окна консоли

        PROCEDURE SetColor(FColor, BColor: INTEGER)
                установка цвета консольного вывода: FColor - цвет текста,
                BColor - цвет фона, возможные значения - вышеперечисленные
                константы

        PROCEDURE SetCursor(x, y: INTEGER)
                установка курсора консоли в позицию (x, y)

        PROCEDURE GetCursor(VAR x, y: INTEGER)
                записывает в параметры текущие координаты курсора консоли

        PROCEDURE GetCursorX(): INTEGER
                возвращает текущую x-координату курсора консоли

        PROCEDURE GetCursorY(): INTEGER
                возвращает текущую y-координату курсора консоли

------------------------------------------------------------------------------
MODULE ConsoleLib - обертка библиотеки console.obj

------------------------------------------------------------------------------
MODULE Math - математические функции

        CONST

                pi = 3.141592653589793E+00
                e  = 2.718281828459045E+00


        PROCEDURE IsNan(x: REAL): BOOLEAN
                возвращает TRUE, если x - не число

        PROCEDURE IsInf(x: REAL): BOOLEAN
                возвращает TRUE, если x - бесконечность

        PROCEDURE sqrt(x: REAL): REAL
                квадратный корень x

        PROCEDURE exp(x: REAL): REAL
                экспонента x

        PROCEDURE ln(x: REAL): REAL
                натуральный логарифм x

        PROCEDURE sin(x: REAL): REAL
                синус x

        PROCEDURE cos(x: REAL): REAL
                косинус x

        PROCEDURE tan(x: REAL): REAL
                тангенс x

        PROCEDURE arcsin(x: REAL): REAL
                арксинус x

        PROCEDURE arccos(x: REAL): REAL
                арккосинус x

        PROCEDURE arctan(x: REAL): REAL
                арктангенс x

        PROCEDURE arctan2(y, x: REAL): REAL
                арктангенс y/x

        PROCEDURE power(base, exponent: REAL): REAL
                возведение числа base в степень exponent

        PROCEDURE log(base, x: REAL): REAL
                логарифм x по основанию base

        PROCEDURE sinh(x: REAL): REAL
                гиперболический синус x

        PROCEDURE cosh(x: REAL): REAL
                гиперболический косинус x

        PROCEDURE tanh(x: REAL): REAL
                гиперболический тангенс x

        PROCEDURE arsinh(x: REAL): REAL
                обратный гиперболический синус x

        PROCEDURE arcosh(x: REAL): REAL
                обратный гиперболический косинус x

        PROCEDURE artanh(x: REAL): REAL
                обратный гиперболический тангенс x

        PROCEDURE round(x: REAL): REAL
                округление x до ближайшего целого

        PROCEDURE frac(x: REAL): REAL;
                дробная часть числа x

        PROCEDURE floor(x: REAL): REAL
                наибольшее целое число (представление как REAL),
                не больше x: floor(1.2) = 1.0

        PROCEDURE ceil(x: REAL): REAL
                наименьшее целое число (представление как REAL),
                не меньше x: ceil(1.2) = 2.0

        PROCEDURE sgn(x: REAL): INTEGER
                если x > 0 возвращает 1
                если x < 0 возвращает -1
                если x = 0 возвращает 0

        PROCEDURE fact(n: INTEGER): REAL
                факториал n

------------------------------------------------------------------------------
MODULE Debug - вывод на доску отладки
        Интерфейс как модуль Out

        PROCEDURE Open
                открывает доску отладки

------------------------------------------------------------------------------
MODULE File - работа с файловой системой

        TYPE

                FNAME = ARRAY 520 OF CHAR

                FS = POINTER TO rFS

                rFS = RECORD (* информационная структура файла *)
                        subfunc, pos, hpos, bytes, buffer: INTEGER;
                        name: FNAME
                END

                FD = POINTER TO rFD

                rFD = RECORD (* структура блока данных входа каталога *)
                        attr: INTEGER;
                        ntyp: CHAR;
                        reserved: ARRAY 3 OF CHAR;
                        time_create, date_create,
                        time_access, date_access,
                        time_modif,  date_modif,
                        size, hsize: INTEGER;
                        name: FNAME
                END

        CONST

                SEEK_BEG = 0
                SEEK_CUR = 1
                SEEK_END = 2

        PROCEDURE Load(FName: ARRAY OF CHAR; VAR size: INTEGER): INTEGER;
                Загружает в память файл с именем FName, записывает в параметр
                size размер файла, возвращает адрес загруженного файла
                или 0 (ошибка). При необходимости, распаковывает
                файл (kunpack).

        PROCEDURE GetFileInfo(FName: ARRAY OF CHAR; VAR Info: rFD): BOOLEAN
                Записывает структуру блока данных входа каталога для файла
                или папки с именем FName в параметр Info.
                При ошибке возвращает FALSE.

        PROCEDURE Exists(FName: ARRAY OF CHAR): BOOLEAN
                возвращает TRUE, если файл с именем FName существует

        PROCEDURE Close(VAR F: FS)
                освобождает память, выделенную для информационной структуры
                файла F и присваивает F значение NIL

        PROCEDURE Open(FName: ARRAY OF CHAR): FS
                возвращает указатель на информационную структуру файла с
                именем FName, при ошибке возвращает NIL

        PROCEDURE Delete(FName: ARRAY OF CHAR): BOOLEAN
                удаляет файл с именем FName, при ошибке возвращает FALSE

        PROCEDURE Seek(F: FS; Offset, Origin: INTEGER): INTEGER
                устанавливает позицию чтения-записи файла F на Offset,
                относительно Origin = (SEEK_BEG - начало файла,
                SEEK_CUR - текущая позиция, SEEK_END - конец файла),
                возвращает позицию относительно начала файла, например:
                        Seek(F, 0, SEEK_END)
                устанавливает позицию на конец файла и возвращает длину
                файла; при ошибке возвращает -1

        PROCEDURE Read(F: FS; Buffer, Count: INTEGER): INTEGER
                Читает данные из файла в память. F - указатель на
                информационную структуру файла, Buffer - адрес области
                памяти, Count - количество байт, которое требуется прочитать
                из файла; возвращает количество байт, которое было прочитано
                и соответствующим образом изменяет позицию чтения/записи в
                информационной структуре F.

        PROCEDURE Write(F: FS; Buffer, Count: INTEGER): INTEGER
                Записывает данные из памяти в файл. F - указатель на
                информационную структуру файла, Buffer - адрес области
                памяти, Count - количество байт, которое требуется записать
                в файл; возвращает количество байт, которое было записано и
                соответствующим образом изменяет позицию чтения/записи в
                информационной структуре F.

        PROCEDURE Create(FName: ARRAY OF CHAR): FS
                создает новый файл с именем FName (полное имя), возвращает
                указатель на информационную структуру файла,
                при ошибке возвращает NIL

        PROCEDURE CreateDir(DirName: ARRAY OF CHAR): BOOLEAN
                создает папку с именем DirName, все промежуточные папки
                должны существовать, при ошибке возвращает FALSE

        PROCEDURE DeleteDir(DirName: ARRAY OF CHAR): BOOLEAN
                удаляет пустую папку с именем DirName,
                при ошибке возвращает FALSE

        PROCEDURE DirExists(DirName: ARRAY OF CHAR): BOOLEAN
                возвращает TRUE, если папка с именем DirName существует

------------------------------------------------------------------------------
MODULE Read - чтение основных типов данных из файла F

        Процедуры возвращают TRUE в случае успешной операции чтения и
        соответствующим образом изменяют позицию чтения/записи в
        информационной структуре F

        PROCEDURE Char(F: File.FS; VAR x: CHAR): BOOLEAN

        PROCEDURE Int(F: File.FS; VAR x: INTEGER): BOOLEAN

        PROCEDURE Real(F: File.FS; VAR x: REAL): BOOLEAN

        PROCEDURE Boolean(F: File.FS; VAR x: BOOLEAN): BOOLEAN

        PROCEDURE Set(F: File.FS; VAR x: SET): BOOLEAN

        PROCEDURE WChar(F: File.FS; VAR x: WCHAR): BOOLEAN

------------------------------------------------------------------------------
MODULE Write - запись основных типов данных в файл F

        Процедуры возвращают TRUE в случае успешной операции записи и
        соответствующим образом изменяют позицию чтения/записи в
        информационной структуре F

        PROCEDURE Char(F: File.FS; x: CHAR): BOOLEAN

        PROCEDURE Int(F: File.FS; x: INTEGER): BOOLEAN

        PROCEDURE Real(F: File.FS; x: REAL): BOOLEAN

        PROCEDURE Boolean(F: File.FS; x: BOOLEAN): BOOLEAN

        PROCEDURE Set(F: File.FS; x: SET): BOOLEAN

        PROCEDURE WChar(F: File.FS; x: WCHAR): BOOLEAN

------------------------------------------------------------------------------
MODULE DateTime - дата, время

        CONST ERR = -7.0E5

        PROCEDURE Now(VAR Year, Month, Day, Hour, Min, Sec: INTEGER)
                записывает в параметры компоненты текущей системной даты и
                времени

        PROCEDURE Encode(Year, Month, Day, Hour, Min, Sec: INTEGER): REAL
                возвращает дату, полученную из компонентов
                Year, Month, Day, Hour, Min, Sec;
                при ошибке возвращает константу ERR = -7.0E5

        PROCEDURE Decode(Date: REAL; VAR Year, Month, Day,
                                Hour, Min, Sec: INTEGER): BOOLEAN
                извлекает компоненты
                Year, Month, Day, Hour, Min, Sec из даты Date;
                при ошибке возвращает FALSE

------------------------------------------------------------------------------
MODULE Args - параметры программы

        VAR argc: INTEGER
                количество параметров программы, включая имя
                исполняемого файла

        PROCEDURE GetArg(n: INTEGER; VAR s: ARRAY OF CHAR)
                записывает в строку s n-й параметр программы,
                нумерация параметров от 0 до argc - 1,
                нулевой параметр -- имя исполняемого файла

------------------------------------------------------------------------------
MODULE KOSAPI

        PROCEDURE sysfunc1(arg1: INTEGER): INTEGER
        PROCEDURE sysfunc2(arg1, arg2: INTEGER): INTEGER
        ...
        PROCEDURE sysfunc7(arg1, arg2, ..., arg7: INTEGER): INTEGER
                Обертки для функций API ядра KolibriOS.
                arg1 .. arg7 соответствуют регистрам
                        eax, ebx, ecx, edx, esi, edi, ebp;
                возвращают значение регистра eax после системного вызова.

        PROCEDURE sysfunc22(arg1, arg2: INTEGER; VAR res2: INTEGER): INTEGER
                Обертка для функций API ядра KolibriOS.
                arg1 - регистр eax, arg2 - регистр ebx,
                res2 - значение регистра ebx после системного вызова;
                возвращает значение регистра eax после системного вызова.

        PROCEDURE malloc(size: INTEGER): INTEGER
                Выделяет блок памяти.
                size - размер блока в байтах,
                возвращает адрес выделенного блока

        PROCEDURE free(ptr: INTEGER): INTEGER
                Освобождает ранее выделенный блок памяти с адресом ptr,
                возвращает 0

        PROCEDURE realloc(ptr, size: INTEGER): INTEGER
                Перераспределяет блок памяти,
                ptr - адрес ранее выделенного блока,
                size - новый размер,
                возвращает указатель на перераспределенный блок,
                0 при ошибке

        PROCEDURE GetCommandLine(): INTEGER
                Возвращает адрес строки параметров

        PROCEDURE GetName(): INTEGER
                Возвращает адрес строки с именем программы

        PROCEDURE LoadLib(name: ARRAY OF CHAR): INTEGER
                Загружает DLL с полным именем name. Возвращает адрес таблицы
                экспорта. При ошибке возвращает 0.

        PROCEDURE GetProcAdr(name: ARRAY OF CHAR; lib: INTEGER): INTEGER
                name - имя процедуры
                lib - адрес таблицы экспорта DLL
                Возвращает адрес процедуры. При ошибке возвращает 0.

------------------------------------------------------------------------------
MODULE ColorDlg - работа с диалогом "Color Dialog"

        TYPE

                Dialog = POINTER TO RECORD (* структура диалога *)
                    status: INTEGER   (* состояние диалога:
                                         0 - пользователь нажал Cancel
                                         1 - пользователь нажал OK
                                         2 - диалог открыт       *)

                    color:  INTEGER   (* выбранный цвет *)
                END

        PROCEDURE Create(draw_window: DRAW_WINDOW): Dialog
                создать диалог
                draw_window - процедура перерисовки основного окна
                (TYPE DRAW_WINDOW = PROCEDURE);
                процедура возвращает указатель на структуру диалога

        PROCEDURE Show(cd: Dialog)
                показать диалог
                cd - указатель на структуру диалога, который был создан ранее
                процедурой Create

        PROCEDURE Destroy(VAR cd: Dialog)
                уничтожить диалог
                cd - указатель на структуру диалога

------------------------------------------------------------------------------
MODULE OpenDlg - работа с диалогом "Open Dialog"

        TYPE

                Dialog = POINTER TO RECORD (* структура диалога *)
                    status:   INTEGER  (* состояние диалога:
                                          0 - пользователь нажал Cancel
                                          1 - пользователь нажал OK
                                          2 - диалог открыт       *)

                    FileName: ARRAY 4096 OF CHAR (* имя выбранного файла *)
                    FilePath: ARRAY 4096 OF CHAR (* полное имя выбранного
                                                    файла           *)
                END

        PROCEDURE Create(draw_window: DRAW_WINDOW; type: INTEGER; def_path,
                        filter: ARRAY OF CHAR): Dialog
                создать диалог
                draw_window - процедура перерисовки основного окна
                        (TYPE DRAW_WINDOW = PROCEDURE)
                type -  тип диалога
                        0 - открыть
                        1 - сохранить
                        2 - выбрать папку
                def_path - путь по умолчанию, папка def_path будет открыта
                        при первом запуске диалога
                filter - в строке записано перечисление расширений файлов,
                        которые будут показаны в диалоговом окне, расширения
                        разделяются символом "|", например: "ASM|TXT|INI"
                процедура возвращает указатель на структуру диалога

        PROCEDURE Show(od: Dialog; Width, Height: INTEGER)
                показать диалог
                od - указатель на структуру диалога, который был создан ранее
                     процедурой Create
                Width и Height - ширина и высота диалогового окна

        PROCEDURE Destroy(VAR od: Dialog)
                уничтожить диалог
                od - указатель на структуру диалога

------------------------------------------------------------------------------
MODULE kfonts - работа с kf-шрифтами

        CONST

                bold            =   1
                italic          =   2
                underline       =   4
                strike_through  =   8
                smoothing       =  16
                bpp32           =  32

        TYPE

                TFont = POINTER TO TFont_desc (* указатель на шрифт *)

        PROCEDURE LoadFont(file_name: ARRAY OF CHAR): TFont
                загрузить шрифт из файла
                file_name   имя kf-файла
                рез-т:          указатель на шрифт/NIL (ошибка)

        PROCEDURE SetSize(Font: TFont; font_size: INTEGER): BOOLEAN
                установить размер шрифта
                Font        указатель на шрифт
                font_size   размер шрифта
                рез-т:          TRUE/FALSE (ошибка)

        PROCEDURE Enabled(Font: TFont; font_size: INTEGER): BOOLEAN
                проверить, есть ли шрифт, заданного размера
                Font        указатель на шрифт
                font_size   размер шрифта
                рез-т:          TRUE/FALSE (шрифта нет)

        PROCEDURE Destroy(VAR Font: TFont)
                выгрузить шрифт, освободить динамическую память
                Font        указатель на шрифт
                Присваивает переменной Font значение NIL

        PROCEDURE TextHeight(Font: TFont): INTEGER
                получить высоту строки текста
                Font        указатель на шрифт
                рез-т:          высота строки текста в пикселях

        PROCEDURE TextWidth(Font: TFont;
                    str, length, params: INTEGER): INTEGER
                получить ширину строки текста
                Font        указатель на шрифт
                str         адрес строки текста в кодировке Win-1251
                length      количество символов в строке или -1, если строка
                            завершается нулем
                params      параметры-флаги см. ниже
                рез-т:          ширина строки текста в пикселях

        PROCEDURE TextOut(Font: TFont;
                    canvas, x, y, str, length, color, params: INTEGER)
                вывести текст в буфер
                для вывода буфера в окно, использовать ф.65 или
                ф.7 (если буфер 24-битный)
                Font        указатель на шрифт
                canvas      адрес графического буфера
                            структура буфера:
                              Xsize       dd
                              Ysize       dd
                              picture     rb  Xsize * Ysize * 4 (32 бита)
                                              или Xsize * Ysize * 3 (24 бита)
                x, y        координаты текста относительно левого верхнего
                            угла буфера
                str         адрес строки текста в кодировке Win-1251
                length      количество символов в строке или -1, если строка
                            завершается нулем
                color       цвет текста 0x00RRGGBB
                params      параметры-флаги:
                               1   жирный
                               2   курсив
                               4   подчеркнутый
                               8   перечеркнутый
                              16   применить сглаживание
                              32   вывод в 32-битный буфер
                            возможно использование флагов в любых сочетаниях
------------------------------------------------------------------------------
MODULE RasterWorks - обертка библиотеки Rasterworks.obj
------------------------------------------------------------------------------
MODULE libimg - обертка библиотеки libimg.obj
------------------------------------------------------------------------------