Технические детали

Текущая версия библиотеки.

Версия библиотеки в целочисленном формате: старшее слово -- номер версии, младшее -- номер ревизии, в двоично-десятичном формате. Например, 0x172a0050 -- версия 0.172a, ревизия 50.

            #define _TX_VERSION "TXLib [Ver: 1.73a, Rev: 164, Date: 2020-01-30 05:00:00 +0300]"  //
            #define _TX_AUTHOR  "Copyright (C) Ded (Ilya Dedinsky, http://txlib.ru)"             //  ПРИМЕР
            #define _TX_VER      0x173a0050                                                      //

Эти константы автоматически обновляются при изменении версии.

См. также:

txVersion()

Примеры использования:

            #if !(defined (_TX_VER) && (_TX_VER >= 0x172a0000))
            #error Must use TXLib.h version >= 1.72 to compile this.
            #endif

См. определение в файле TXLib.h строка 145

Имя модуля TXLib. Входит в диагностические сообщения.

Заметки:

Можно переопределять до включения файла TXLib.h.

См. определение в файле TXLib.h строка 166

Запрет ранней инициализации TXLib.

Если константа определена с помощью #define до включения TXLib.h в программу, ранняя инициализация (до запуска функции main) не проводится.

Заметки:

Ранняя инициализация включает:

• Открытие окна консоли,
• Установку кодовой страницы _TX_CODEPAGE (1251) консоли для поддержки русского языка,
• Установку русской локали стандартной библиотеки C++ ("Russian" / "ru_RU.CP1251" и L"Russian_Russia.ACP"),
• Переинициализация библиотек stdio и iostream на случай, если приложение не скомпоновано как консольное и библиотеки остались не инициализированы,
• Перехват системных сигналов (деление на 0, арифметические ошибки, обращение по неверному адресу и т.д.),
• Перехват необработанных исключений,
• Смена заголовка консольного окна,
• Установка режима паузы по завершении программы, чтобы окно закрывалось не сразу,
• Подавление паузы при запуске из сред программирования, заставляющей нажимать на клавишу два раза.
  

Если ранняя инициализация запрещена, но в EXE-файле создается окно TXLib с помощью txCreateWindow(), то библиотека все равно будет инициализирована. В DLL ранняя инициализация никогда не проводится.

Ранняя инициализация не потокобезопасна (not thread-safe).

См. также:

txCreateWindow(), _TX_ALLOW_KILL_PARENT, _TX_WAITABLE_PARENTS, _txWatchdogTimeout, TX_CONSOLE_MODE

Примеры использования:

          #define _TX_NOINIT
          #include "TXLib.h"

См. определение в файле TXLib.h строка 5677

Режим отображения консольного окна. Допустимы любые флаги функции ShowWindow.

По умолчанию: SW_HIDE -- Скрывать консольное окно после показа графического окна.

Если ваше приложение консольное, то оно будет запускаться с открытым   черным печальным   консольным окном, которое скроется при открытии графического окна. Это может выглядеть как мигание консольного окна. Чтобы этого не было, можно создать неконсольное приложение, которое изначально запускается без видимого консольного окна и при его запуске нет эффекта такого мигания.

Создать неконсольное приложение можно:

Для компиляторов g++ (MinGW, Cygwin) и clang, используемых в CodeBlocks, CLion и т.п.	-- Указав компилятору ключ -mwindows и убрав ключ -mconsole.
Для компиляторов семейства Microsoft Visual Studio	-- Создав не проект консольного приложения, а "Desktop Application" или аналогичный.

Заметки:

Константа задается до включения файла TXLib.h в программу.

Предупреждения:

Если вы создали неконсольное приложение (см. выше), но запускаете его из среды программирования (например, CodeBlocks), то вы можете увидеть другое консольное окно служебной программы, с помощью которой среда программирования запускает ваше приложение. Если вы запустите ваше неконсольное приложение не из среды программирования, а непосредственно из Проводника, то вы не увидите никаких лишних консольных окон.

Заметки:

Btw, if you do not like that console window text is painted over graphic canvas window, set the undocumented variable _txConsole to negative value.

См. также:

_TX_NOINIT

Примеры использования:

          #define TX_CONSOLE_MODE  SW_HIDE          // Скрыть консольное окно при открытии графического окна
          #include "TXLib.h"                        // (Поведение по умолчанию)
          ...
          txCreateWindow (800, 600);

          #define TX_CONSOLE_MODE  SW_SHOW          // Всегда показывать консольное окно, например, для отладки
          #include "TXLib.h"
          ...
          txCreateWindow (800, 600);

См. определение в файле TXLib.h строка 5729

Шрифт консоли

Заметки:

Константа задается до включения файла TXLib.h в программу.

См. определение в файле TXLib.h строка 5741

Макрос, разрешающий использовать TXLib вместе с графической библиотекой SFML

Заметки:

Этот макрос задается перед включением TXLib.h в программу.

Примеры использования:

          #define  TX_USE_SFML
          #include "TXLib.h"
          #include <SFML/Graphics.hpp>

См. определение в файле TXLib.h строка 5805

"Winpty-agent.exe:Clion.exe, "            /* 0: CLion32       */ \
                                          "Winpty-agent.exe:Clion64.exe, "          /* 1: CLion64       */ \
                                          "starter.exe:eclipse.exe, "               /* 2: Eclipse 4     */ \
                                          "starter.exe:javaw.exe, "                 /* 3: Eclipse 3     */ \
                                          "cmd.exe:devenv.exe, "                    /* 4: MSVS 2003+    */ \
                                          "VSDebugConsole.exe:devenv.exe, "         /* 5: MSVS 2019+    */ \
                                          "VSDebugConsole.exe:msvsmon.exe, "        /* 6: MSVS 2022 x86 */ \
                                          "consolepauser.exe:devcpp.exe, "          /* 7: Dev-Cpp       */ \
                                          "cb_console_runner.exe:codeblocks.exe"

Список запускающих программ, которые ждут нажатия клавиши после завершения процесса TXLib.

Если программа перечислена в списке и TXLib запущена из нее, то при завершении TXLib указанная программа будет закрыта. (Это произойдет, если не открыто графическое окно TXLib, а есть только окно консоли.)

Программы разделяются пробелом или запятой. Допускается указание родителя запускающей программы, после двоеточия. Имя программы, начинающееся с большой буквы - спец. случай для консоли CLion, см. функции _txCleanup() и _txIsParentWaitable() в исходном тексте TXLib.h.

Может задаваться перед включением TXLib.h в программу.

См. также:

_TX_ALLOW_KILL_PARENT, _TX_NOINIT, _txCleanup(), _txIsParentWaitable(), _txWatchdogTimeout

См. определение в файле TXLib.h строка 5944

Разрешать принудительное завершение вызывающих программ, ждущих нажатия клавиш после завершения TXLib.

Иначе отменяется собственная пауза до нажатия клавиши, встроенная в TXLib, и пусть тогда паузу делает вызывающий процесс.

Список вызывающих программ, которые могут делать такую паузу, задается в _TX_WAITABLE_PARENTS.

Заметки:

Макрос должен задаваться перед включением TXLib.h в программу.

См. также определение этой константы в файле TXLib.h.

См. также:

_TX_WAITABLE_PARENTS, _TX_NOINIT, _txWatchdogTimeout

Примеры использования:

          #define _TX_ALLOW_KILL_PARENT false
          #include "TXLib.h"

См. определение в файле TXLib.h строка 5977

Макросы для поддержки прекомпиляции TX Library.

Не секрет, что файл TXLib.h очень большой и, как следствие, долго компилируется. Для ускорения сборки проектов обычно используется техника раздельной компиляции, когда в проект входят не один, а несколько .cpp-файлов. В этом случае, если изменен только один такой файл, перекомпилироваться будет только он, а результаты компиляции остальных файлов присоединяются на этапе линковки, что гораздо быстрее.

Однако библиотека TX Library представляет собой единственный заголовочный .h-файл, а заголовочные файлы перекомпилирются каждый раз, при каждой сборке. Это существенно замедляло работу с библиотекой.

Теперь файл TXLib.h внутри разделен на части, которые могут по-разному вести себя при компиляции.

Если при компиляции перед включением файла TXLib.h определен макрос TX_COMPILED, то компилироваться будет меньшая часть файла, порядка одной трети. Эта часть содержит то, что обязательно надо включать в каждую компиляцию: определения констант, структур и классов, прототипы функций, шаблоны, макросы и др. При этом около двух третей файла, которые содержат определения нешаблонных функций, не будут компилироваться. (Строго говоря, код этих двух третей обычно не помещают в заголовочные файлы, но, так как библиотека построена по принципу единственного файла для упрощения работы с ней, такой код она вынуждена содержать.)

Чтобы в проекте были доступны откомпилированные определения всех необходимых функций библиотеки, в него нужно добавить еще один файл, включив в него @с TXLib.h и определив в нем макрос TX_COMPILING. Это приведет к компиляции всего содержимого библиотеки, и ее машинный код станет доступен всей программе. В примере ниже этот файл назван TXLib.cpp, но имя может быть любое. Для компиляции этого файла потребуется время, но затем он перестанет участвовать в компиляции, так как его содержимое не будет изменяться, и общее время сборки проекта сократится, от 1.5 до 3 раз.

Предупреждения:

Не следует помещать в этот файл ничего, кроме директив #define TX_COMPILING и #include "TXLib.h", так как при изменении содержимого этого файла среда программирования снова перекомпилирует его, на что вновь потребуется большое время.

Также для ускорения компиляции можно определить макрос WIN32_LEAN_AND_MEAN до включения TXLib.h в программу.

Предупреждения:

Макрос WIN32_LEAN_AND_MEAN задается автоматически при задании макроса TX_COMPILED. Если при этом не видны определения каких-либо сущностей, определенных в Windows.h (функций, структур, классов, констант и т.п.), включите в программу файлы, определяющие эти сущности, вручную.

Заметки:

Если определены макросы TX_COMPILED или TX_COMPILING, анонимное пространство имен, окружающее пространство имен TX, не используется.

Примеры использования:

          // Оба файла ниже должны входить в один и тот же проект Visual Studio или другой среды
          // программирования (IDE). Для добавления файла в проект используйте возможности вашей среды
          // программирования.

          //-----------------------------------------------
          // Main.cpp: Файл с текстом программы
          //-----------------------------------------------

          #define   TX_COMPILED   // Обязательно ПЕРЕД командой #include
          #include "TXLib.h"

          int main()
              {
              txCreateWindow (800, 600);
              ...
              }

          //-----------------------------------------------
          // TXLib.cpp: Файл для прекомпиляции TXLib
          //-----------------------------------------------

          #define   TX_COMPILING  // Обязательно ПЕРЕД командой #include
          #include "TXLib.h"

          // [Больше в этом файле ничего нет]

См. определение в файле TXLib.h строка 6074

Включает/отключает внутреннюю трассировку исполнения кода библиотеки.

Трассировка идет через макрос TX_TRACE, который подставляется перед каждым оператором (statement). По умолчанию трассировка выключена.

По умолчанию трассировка ведется через функцию OutputDebugString(), ее вывод можно перехватить утилитами-логгерами, например, DbgView. Это можно изменить, переопределив макрос TX_TRACE до включения TXLib.h в программу.

Предупреждения:

Трассировка очень тормозит выполнение программы, особенно при отладке в Microsoft Visual Studio. В этом случае лучше пользоваться DbgView (см. выше) и запускать отлаживаемую программу отдельно, а не из-под отладчика Visual Studio.

Заметки:

_TX_ALLOW_TRACE и TX_TRACE задаются перед включением TXLib.h в программу.

Уровни трассировки:

1	Regular functions
2	Reserved
3	Init/Cleanup
4	Init/Cleanup, misc functions
5	Error handling, entry points
6	Error handling, main part
7	Error handling, misc functions
8	Canvas worker thread
9	Reserved

Примеры использования:

          // Для просмотра трассы запустите DbgView ДО запуска программы!

          #define  _TX_ALLOW_TRACE 1  // Трассировать только обычные функции TXLib (уровень 1).
          #include "TXLib.h"

          #define  _DEBUG             // Не трассировать, но собирать информацию о вызовах
          #include "TXLib.h"          // функций TXLib для возможной трассировки стека.

См. определение в файле TXLib.h строка 6132

Трассирует исполнение кода через OutputDebugString().

По умолчанию трассировка ведется через функцию OutputDebugString(), ее вывод можно перехватить утилитами-логгерами, например, DbgView. Для "раскраски" лога есть файл TX\Dev\DbgView.ini, его надо загрузить в DbgView через меню Edit/Filter/Load (Ctrl+L).

С помощью TX_TRACE можно трассировать код самой библиотеки TXLib. Для этого надо разрешить трассировку TXLib, определив макрос _TX_ALLOW_TRACE перед включением файла TXLib.h в программу. По умолчанию трассировка TXLib выключена.

TX_TRACE можно переопределить в свой код. Тогда, если трассировка библиотеки разрешена, он будет вызываться почти перед каждой исполняемой строкой TXLib. Может быть, это кому-нибудь будет интересно.

Примеры использования:

          int main()
              {
              ...
              TX_TRACE;  // Через DbgView увидим имя файла и номер выполняемой строки
              ...
              }

          #define  TX_TRACE  printf (__TX_FILELINE__ "\t" __TX_FUNCTION__ "\n");
          #include "TXLib.h"

См. определение в файле TXLib.h строка 6168

Возвращает строку с информацией о текущей версии библиотеки.

Возвращает:

Строка с информацией о текущей версии библиотеки.

Примеры использования:

          printf ("I personally love %s\n", txVersion());

Возвращает номер версии библиотеки.

Возвращает:

Номер версии библиотеки.

Примеры использования:

          printf ("My magic number is %x\n", txVersionNumber());

Возвращает имя исполняемого файла или изначальный заголовок окна TXLib.

Аргументы:

fileNameOnly

Возвратить только полное имя исполняемого файла, полученного через Win32 функцию GetFileModuleName (NULL, ...). Необязательно. Если не указано, то возвращается полное имя исполняемого файла.

Возвращает:

fileNameOnly = true: Имя исполняемого файла.
fileNameOnly = false: Изначальный заголовок окна TXLib.

Заметки:

Возвращается статическая строка.

См. также:

txWindow(), txVersion(), txVersionNumber()

Примеры использования:

          printf ("Смотрите на заголовок окна!");

          for (int done = 0; done <= 100; done++)
              {
              char title [1024] = "";
              sprintf (title, "%s - [%-10.*s] %d%%", txGetModuleFileName (false), done/10, "||||||||||", done);

              SetWindowText (txWindow(), title);
              SetWindowText (Win32::GetConsoleWindow(), title);
              txSleep (50);
              }

          txMessageBox ("Вот такой вот progress bar", "TXLib forever)");

Имя лог-файла TXLib.

В эту строку надо скопировать нужное вам имя лог-файла.

По умолчанию файл создается во время ошибки в одной папке с запущенной программой, имеет то же имя, что и файл программы, с добавлением расширения ".log".

Заметки:

Устанавливать имя лог-файла надо в начале работы программы, до появления первой ошибки.

См. определение в файле TXLib.h строка 5630

Стиль графического окна библиотеки.

Заметки:

Переменная устанавливается до открытия окна библиотеки.

Примеры использования:

          _txWindowStyle &= ~WS_CAPTION; // FullScreen: окно без заголовка, размером с экран
          txCreateWindow (GetSystemMetrics (SM_CXSCREEN), GetSystemMetrics (SM_CYSCREEN));

          printf ("Закройте меня через Alt+F4\n");

См. определение в файле TXLib.h строка 5760

Интервал обновления холста (мс)

Заметки:

Переменная устанавливается до открытия окна библиотеки.

См. определение в файле TXLib.h строка 5787

Указатель на функцию, выводящую изображение непосредственно в окно TXLib во время обработки WM_PAINT.

Если равен NULL, то используется Win32::BitBlt.

Вы можете переопределить значение этого указателя, чтобы он указывал на вашу функцию, и тогда TXLib будет выводить изображение в окно через нее. Имейте в виду, что эта функция будет вызываться в отдельном потоке.

Параметры этой функции гуглите: "StretchBlt function".

См. также:

txSetWindowsHook(), txBitBlt(), txAlphaBlend()

Примеры использования:

          #include "TXLib.h"

          bool MySwapBuffers (HDC dest, int xDest, int yDest, int wDest, int hDest,
                              HDC src,  int xSrc,  int ySrc,  int wSrc,  int hSrc, DWORD rOp)
              {
              return txAlphaBlend (dest, xDest, yDest, wSrc-xSrc, hSrc-ySrc, src, xSrc, ySrc, 0.01);
              }

          int main()
              {
              _txSwapBuffers = MySwapBuffers;  // That's it

              txCreateWindow (800, 600);

              txSetFillColor (TX_NULL);
              txRectangle (10, 10, txGetExtentX() - 10, txGetExtentY() - 10);

              for (int x = 50; x <= txGetExtentX() - 50; x += 20)
                  {
                  txCircle (x, txGetExtentY()/2, 10);
                  txSleep (100);
                  }

              txSleep (3000);
              }

См. определение в файле TXLib.h строка 5873

Лимит времени на завершение программы, начиная от завершения функции main() или от вызова exit(), в мс.

Если значение меньше 0, то время не лимитируется.

Заметки:

Для предотвращения зависания программы при выходе TXLib запускает отдельный сторожевой поток (watchdog thread), который ожидает _txWatchdogTimeout миллисекунд, а затем принудительно завершает программу.

См. также:

_TX_WAITABLE_PARENTS, _TX_NOINIT

См. определение в файле TXLib.h строка 5994