README.html

   1 <!DOCTYPE html>
   2 <html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
   3 <head>
   4   <meta charset="utf-8" />
   5   <meta name="generator" content="pandoc" />
   6   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
   7   <meta name="author" content="Created by LoRd_MuldeR &lt;mulder2@gmx&gt; – check http://muldersoft.com/ for news and updates!" />
   8   <title>MUtilities – README</title>
   9   <style>
  10     html {
  11       line-height: 1.5;
  12       font-family: Georgia, serif;
  13       font-size: 20px;
  14       color: #1a1a1a;
  15       background-color: #fdfdfd;
  16     }
  17     body {
  18       margin: 0 auto;
  19       max-width: 36em;
  20       padding-left: 50px;
  21       padding-right: 50px;
  22       padding-top: 50px;
  23       padding-bottom: 50px;
  24       hyphens: auto;
  25       overflow-wrap: break-word;
  26       text-rendering: optimizeLegibility;
  27       font-kerning: normal;
  28     }
  29     @media (max-width: 600px) {
  30       body {
  31         font-size: 0.9em;
  32         padding: 1em;
  33       }
  34       h1 {
  35         font-size: 1.8em;
  36       }
  37     }
  38     @media print {
  39       body {
  40         background-color: transparent;
  41         color: black;
  42         font-size: 12pt;
  43       }
  44       p, h2, h3 {
  45         orphans: 3;
  46         widows: 3;
  47       }
  48       h2, h3, h4 {
  49         page-break-after: avoid;
  50       }
  51     }
  52     p {
  53       margin: 1em 0;
  54     }
  55     a {
  56       color: #1a1a1a;
  57     }
  58     a:visited {
  59       color: #1a1a1a;
  60     }
  61     img {
  62       max-width: 100%;
  63     }
  64     h1, h2, h3, h4, h5, h6 {
  65       margin-top: 1.4em;
  66     }
  67     h5, h6 {
  68       font-size: 1em;
  69       font-style: italic;
  70     }
  71     h6 {
  72       font-weight: normal;
  73     }
  74     ol, ul {
  75       padding-left: 1.7em;
  76       margin-top: 1em;
  77     }
  78     li > ol, li > ul {
  79       margin-top: 0;
  80     }
  81     blockquote {
  82       margin: 1em 0 1em 1.7em;
  83       padding-left: 1em;
  84       border-left: 2px solid #e6e6e6;
  85       color: #606060;
  86     }
  87     code {
  88       font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
  89       font-size: 85%;
  90       margin: 0;
  91     }
  92     pre {
  93       margin: 1em 0;
  94       overflow: auto;
  95     }
  96     pre code {
  97       padding: 0;
  98       overflow: visible;
  99       overflow-wrap: normal;
 100     }
 101     .sourceCode {
 102      background-color: transparent;
 103      overflow: visible;
 104     }
 105     hr {
 106       background-color: #1a1a1a;
 107       border: none;
 108       height: 1px;
 109       margin: 1em 0;
 110     }
 111     table {
 112       margin: 1em 0;
 113       border-collapse: collapse;
 114       width: 100%;
 115       overflow-x: auto;
 116       display: block;
 117       font-variant-numeric: lining-nums tabular-nums;
 118     }
 119     table caption {
 120       margin-bottom: 0.75em;
 121     }
 122     tbody {
 123       margin-top: 0.5em;
 124       border-top: 1px solid #1a1a1a;
 125       border-bottom: 1px solid #1a1a1a;
 126     }
 127     th {
 128       border-top: 1px solid #1a1a1a;
 129       padding: 0.25em 0.5em 0.25em 0.5em;
 130     }
 131     td {
 132       padding: 0.125em 0.5em 0.25em 0.5em;
 133     }
 134     header {
 135       margin-bottom: 4em;
 136       text-align: center;
 137     }
 138     #TOC li {
 139       list-style: none;
 140     }
 141     #TOC ul {
 142       padding-left: 1.3em;
 143     }
 144     #TOC > ul {
 145       padding-left: 0;
 146     }
 147     #TOC a:not(:hover) {
 148       text-decoration: none;
 149     }
 150     code{white-space: pre-wrap;}
 151     span.smallcaps{font-variant: small-caps;}
 152     span.underline{text-decoration: underline;}
 153     div.column{display: inline-block; vertical-align: top; width: 50%;}
 154     div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
 155     ul.task-list{list-style: none;}
 156     .display.math{display: block; text-align: center; margin: 0.5rem auto;}
 157   </style>
 158   <style type="text/css">
 159   <!--
 160     body { font-family: "Times New Roman", Times, serif; color: #000000; background-color: #FFFFFF; }
 161     p { text-align: justify; }
 162     tt, pre, code { font-family: Courier New, Courier, mono; background-color: #EDF3F7; padding: 1px; }
 163     h1:not(.title) { margin-top: 2.25em; }
 164     h2:not(.author) { margin-top: 2.0em; }
 165     h3, h4 { margin-top: 1.75em; }
 166     a { color: #0000BB; text-decoration: none; }
 167     a:visited { color: #0000BB; text-decoration: none; }
 168     a:active { color: #0000FF; text-decoration: none; }
 169     a:hover { color: #0000FF; text-decoration: underline; }
 170     img { margin-bottom: 0.75em; }
 171     ul, ol  { margin-bottom: 2.0em; }
 172     li>ul, li>ol  { margin-bottom: 0em; }
 173   -->
 174   </style>
 175   <!--[if lt IE 9]>
 176     <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
 177   <![endif]-->
 178 </head>
 179 <body>
 180 <header id="title-block-header">
 181 <h1 class="title">MUtilities – README</h1>
 182 <p class="author">Created by LoRd_MuldeR &lt;<a
 183 href="mailto:mulder2@gmx" class="email">mulder2@gmx</a>&gt; – check <a
 184 href="http://muldersoft.com/" class="uri">http://muldersoft.com/</a> for
 185 news and updates!</p>
 186 </header>
 187 <nav id="TOC" role="doc-toc">
 188 <ul>
 189 <li><a href="#introduction" id="toc-introduction"><span
 190 class="toc-section-number">1</span> Introduction</a></li>
 191 <li><a href="#project-structure" id="toc-project-structure"><span
 192 class="toc-section-number">2</span> Project Structure</a></li>
 193 <li><a href="#example" id="toc-example"><span
 194 class="toc-section-number">3</span> Example</a>
 195 <ul>
 196 <li><a href="#build-notes" id="toc-build-notes"><span
 197 class="toc-section-number">3.1</span> Build Notes</a></li>
 198 </ul></li>
 199 <li><a href="#api-documentation" id="toc-api-documentation"><span
 200 class="toc-section-number">4</span> API Documentation</a></li>
 201 <li><a href="#license" id="toc-license"><span
 202 class="toc-section-number">5</span> License</a></li>
 203 <li><a href="#acknowledgement" id="toc-acknowledgement"><span
 204 class="toc-section-number">6</span> Acknowledgement</a></li>
 205 </ul>
 206 </nav>
 207 <h1 data-number="1" id="introduction"><span
 208 class="header-section-number">1</span> Introduction</h1>
 209 <p>The <strong>MUtilities</strong> library is a collection of routines
 210 and classes to extend the <a href="http://qt-project.org/"><em>Qt
 211 cross-platform framework</em></a>. It contains various convenience and
 212 utility functions as well as wrappers for OS-specific functionalities.
 213 The library was originally created as a "side product" of the <a
 214 href="http://lamexp.sourceforge.net/"><strong>LameXP</strong></a>
 215 application: Over the years, a lot of code, <strong>not</strong> really
 216 specific to <em>LameXP</em>, had accumulated in the <em>LameXP</em> code
 217 base. Some of that code even had been used in other projects too, in a
 218 "copy &amp; paste" fashion – which had lead to redundancy and much
 219 complicated maintenance. In order to clean-up the LameXP code base, to
 220 eliminate the ugly redundancy and to simplify maintenance, the code in
 221 question has finally been refactored into the
 222 <strong>MUtilities</strong> (aka "MuldeR's Utilities for Qt") library.
 223 This library now forms the foundation of <em>LameXP</em> and <a
 224 href="https://github.com/lordmulder"><em>other OpenSource
 225 projects</em></a>.</p>
 226 <h1 data-number="2" id="project-structure"><span
 227 class="header-section-number">2</span> Project Structure</h1>
 228 <p>The <em>MUtilities</em> project directory is organized as
 229 follows:</p>
 230 <ul>
 231 <li><code>bin/</code> – compiled library files (static or shared), link
 232 those files in projects that use the MUtilities library</li>
 233 <li><code>docs/</code> – programming interface documentation, generated
 234 with Doxygen tool</li>
 235 <li><code>etc/</code> – miscellaneous files, everything that doesn't fit
 236 in anywhere else</li>
 237 <li><code>include/</code> – public header files, include this directory
 238 in projects that use the MUtilities library</li>
 239 <li><code>obj/</code> – object code files, intermediate files generated
 240 during the build process</li>
 241 <li><code>res/</code> – resource files, required for building the
 242 MUtilities library</li>
 243 <li><code>src/</code> – source code files, required for building the
 244 MUtilities library (third-party code in
 245 <code>src/3rd_party/</code>)</li>
 246 <li><code>test/</code> – unit tests, based on Google Test framework</li>
 247 <li><code>tmp/</code> – temporary files, automatically generated during
 248 the build process</li>
 249 </ul>
 250 <h1 data-number="3" id="example"><span
 251 class="header-section-number">3</span> Example</h1>
 252 <p>Here is a minimal example on how to use the <em>MUtilities</em>
 253 library in your project:</p>
 254 <pre><code>//MUtils
 255 #include &lt;MUtils/Global.h&gt;
 256
 257 int main(int argc, char **argv)
 258 {
 259     qDebug(&quot;Random number: %u\n&quot;, MUtils::next_rand_u32());
 260 }</code></pre>
 261 <h2 data-number="3.1" id="build-notes"><span
 262 class="header-section-number">3.1</span> Build Notes</h2>
 263 <ul>
 264 <li>In order to use the <em>MUtilities</em> library in your project,
 265 your build environment must have already been set up for building
 266 Qt-based projects. Setting up Qt is <em>not</em> covered by this
 267 document.</li>
 268 <li>Additionally, make sure that <em>MUtilities'</em>
 269 <code>include/</code> directory is contained in your "Additional Include
 270 Directories" and that the <em>MUtilities'</em> <code>bin/</code>
 271 directory is contained in your "Additional Library Directories".</li>
 272 <li>Finally, make sure that your project links against the
 273 <code>MUtils32-1.lib</code> library file. For each build configuration,
 274 pick the proper <strong>.lib</strong> file from the corresponding
 275 <code>bin/&lt;platform&gt;/&lt;config&gt;/</code> directory!</li>
 276 <li>If your projects intends to use the <em>MUtilities</em> library as a
 277 <strong>static</strong> library, then the macro
 278 <code>MUTILS_STATIC_LIB</code> <em>must</em> be added to your project's
 279 "Preprocessor Definitions".</li>
 280 </ul>
 281 <h1 data-number="4" id="api-documentation"><span
 282 class="header-section-number">4</span> API Documentation</h1>
 283 <p>A fully-fledged documentation of the <em>MUtilities</em> programming
 284 interface (API) is available thanks to <a
 285 href="http://www.stack.nl/~dimitri/doxygen/"><em>Doxygen</em></a>.
 286 Please see <a
 287 href="docs/index.html"><strong><code>docs/index.html</code></strong></a>
 288 for details!</p>
 289 <h1 data-number="5" id="license"><span
 290 class="header-section-number">5</span> License</h1>
 291 <p>This library is free software. It is released under the terms of the
 292 <a href="https://www.gnu.org/licenses/lgpl-2.1.html"><em>GNU Lesser
 293 General Public License (LGPL), Version 2.1</em></a>.</p>
 294 <pre><code>MUtilities - MuldeR&#39;s Utilities for Qt
 295 Copyright (C) 2004-2022 LoRd_MuldeR &lt;MuldeR2@GMX.de&gt;. Some rights reserved.
 296
 297 This library is free software; you can redistribute it and/or
 298 modify it under the terms of the GNU Lesser General Public
 299 License as published by the Free Software Foundation; either
 300 version 2.1 of the License, or (at your option) any later version.
 301
 302 This library is distributed in the hope that it will be useful,
 303 but WITHOUT ANY WARRANTY; without even the implied warranty of
 304 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 305 Lesser General Public License for more details.
 306
 307 You should have received a copy of the GNU Lesser General Public
 308 License along with this library; if not, write to the Free Software
 309 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA.</code></pre>
 310 <h1 data-number="6" id="acknowledgement"><span
 311 class="header-section-number">6</span> Acknowledgement</h1>
 312 <p>The following people have contributed in the development of the
 313 MUtilities library:</p>
 314 <ul>
 315 <li><strong>John Buonagurio &lt;<a
 316 href="mailto:jbuonagurio@exponent.com"
 317 class="email">jbuonagurio@exponent.com</a>&gt;</strong><br />
 318 Support for Qt5</li>
 319 </ul>
 320 <p>The following third-party code is used in the MUtilities library:</p>
 321 <ul>
 322 <li><p><strong>Keccak/SHA-3 Reference Implementation</strong><br />
 323 Implementation by the Keccak, Keyak and Ketje Teams, namely, Guido
 324 Bertoni, Joan Daemen, Michaël Peeters, Gilles Van Assche and Ronny Van
 325 Keer<br />
 326 No Copyright / Dedicated to the Public Domain</p></li>
 327 <li><p><strong>Natural Order String Comparison</strong><br />
 328 Copyright (C) 2000, 2004 by Martin Pool &lt;<a
 329 href="mailto:mbp@sourcefrog.net"
 330 class="email">mbp@sourcefrog.net</a>&gt;<br />
 331 Released under the zlib License</p></li>
 332 <li><p><strong>Adler-32 Checksum Algorithm (from zlib)</strong><br />
 333 Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler<br />
 334 Released under the zlib License</p></li>
 335 </ul>
 336 <p> </p>
 337 <p><strong>e.o.f.</strong></p>
 338 </body>
 339 </html>