diff --git a/Doxyfile b/Doxyfile index 89b199a..860e32f 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1392,7 +1392,8 @@ HTML_EXTRA_FILES = doxygen-awesome-darkmode-toggle.js \ doxygen-awesome-fragment-copy-button.js \ doxygen-awesome-paragraph-link.js \ doxygen-custom/toggle-alternative-theme.js \ - doxygen-awesome-interactive-toc.js + doxygen-awesome-interactive-toc.js \ + doxygen-awesome-tabs.js # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output # should be rendered with a dark or light theme. diff --git a/README.md b/README.md index 90a6f03..14dcd6d 100644 --- a/README.md +++ b/README.md @@ -64,40 +64,39 @@ There is two layout options. Choose one of them and configure Doxygen accordingl +
+- 1️⃣ Base Theme + Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled. -#### Base Theme (1) + Required files: `doxygen-awesome.css` -Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled. + Required `Doxyfile` configuration: + ``` + GENERATE_TREEVIEW = YES # optional. Also works without treeview + DISABLE_INDEX = NO + FULL_SIDEBAR = NO + HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css + HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 + ``` -Required files: `doxygen-awesome.css` +- 2️⃣ Sidebar-Only Theme + Hides the top titlebar to give more space to the content. The treeview must be enabled in order for this theme to work. -Required `Doxyfile` configuration: -``` -GENERATE_TREEVIEW = YES # optional. Also works without treeview -DISABLE_INDEX = NO -FULL_SIDEBAR = NO -HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css -HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 -``` - -#### Sidebar-Only Theme (2) - -Hides the top titlebar to give more space to the content. The treeview must be enabled in order for this theme to work. + Required files: `doxygen-awesome.css`, `doxygen-awesome-sidebar-only.css` -Required files: `doxygen-awesome.css`, `doxygen-awesome-sidebar-only.css` + Required `Doxyfile` configuration: + ``` -Required `Doxyfile` configuration: -``` - -GENERATE_TREEVIEW = YES # required! -DISABLE_INDEX = NO -FULL_SIDEBAR = NO -HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ - doxygen-awesome-css/doxygen-awesome-sidebar-only.css -HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 -``` + GENERATE_TREEVIEW = YES # required! + DISABLE_INDEX = NO + FULL_SIDEBAR = NO + HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ + doxygen-awesome-css/doxygen-awesome-sidebar-only.css + HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 + ``` +
**Caution**: - This theme is not compatible with the `FULL_SIDEBAR = YES` option provided by Doxygen! diff --git a/docs/customization.md b/docs/customization.md index d0107f0..15e5014 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -28,13 +28,16 @@ html { For dark-mode overrides you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not: -- dark-mode toggle is installed: +
+ +- dark-mode toggle is installed ```css html.dark-mode { /* define dark-mode variable overrides here if you DO use doxygen-awesome-darkmode-toggle.js */ } ``` -- dark-mode toggle is **NOT** installed. The dark-mode is enabled automatically depending on the system preference: +- dark-mode toggle is **NOT** installed + The dark-mode is enabled automatically depending on the system preference: ```css @media (prefers-color-scheme: dark) { html:not(.light-mode) { @@ -43,6 +46,8 @@ For dark-mode overrides you have to choose where to put them, depending on wheth } ``` +
+ ### Available variables The following list gives an overview of the variables defined in [`doxygen-awesome.css`](https://github.com/jothepro/doxygen-awesome-css/blob/main/doxygen-awesome.css). @@ -73,7 +78,7 @@ All variables are defined at the beginning of the stylesheet. | **Code Fragment Colors**:
Color-Scheme of multiline codeblocks ||| | `--fragment-background` | #F8F9FA | #282c34 | | `--fragment-foreground` | #37474F | #dbe4eb | -| **Arrow Opacity**:
By default the arrows in the sidebar are only visible on hover. You can override this behaviour so they are visible all the time. ||| +| **Arrow Opacity**:
By default the arrows in the sidebar are only visible on hover. You can override this behavior so they are visible all the time. ||| | `--side-nav-arrow-opacity` | `0` | | | `--side-nav-arrow-hover-opacity` | `0.9` | | | ...and many more ||| diff --git a/docs/extensions.md b/docs/extensions.md index 6dbc378..4383cc3 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -184,6 +184,52 @@ Hiding the TOC on small screens can be disabled. It is still interactive and can DoxygenAwesomeInteractiveToc.hideMobileMenu = false ``` +## Tabs + +@note Experimental feature! Please report bugs [here](https://github.com/jothepro/doxygen-awesome-css/issues). + + +This extension allows to arrange list content in tabs: + +
+ +- Tab 1 This is the content of tab 1 +- Tab 2 This is the content of tab 2 + +
+ + +### Installation + +1. Add the required resources in your `Doxyfile`: + - **HTML_EXTRA_FILES:** `doxygen-awesome-tabs.js` +2. In the `header.html` template, include `doxygen-awesome-tabs.js` at the end of the `` and then initialize it: + ```html + + + + + + + + ``` + +### Usage + +Each List that is supposed to be displayed as tabs has to be wrapped with the `tabbed` CSS class. +Each Item in the list must start with an element that has the class `tab-title`. It will then be used as tab title. + +```md +
+ +- Tab 1 This is the content of tab 1 +- Tab 2 This is the content of tab 2 + +
+``` + Read Next: [Customization](customization.md) diff --git a/docs/tricks.md b/docs/tricks.md index 79c1c85..9890d4f 100644 --- a/docs/tricks.md +++ b/docs/tricks.md @@ -13,18 +13,21 @@ DOT_IMAGE_FORMAT = svg DOT_TRANSPARENT = YES ``` -In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, make sure to add this CSS snippet in order for the interactive svg viewer to be -rendered correctly: +In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, all user-defined dotgraphs must be wrapped with the `interactive_dotgraph` CSS class in order for them to be rendered correctly: -```css -.dotgraph iframe { - max-width: 100%; -} +```md +
+ +\dotfile graph.dot + +
``` +@note Both the default overflow scrolling behavior in this theme and the interactive editor enabled by `INTERACTIVE_SVG` are unsatisfying workarounds IMHO. Consider designing your graphs to be narrow enough to fit the page to avoid scrolling. + ## Disable Dark Mode -If for some reason you don't want the theme to automatically switch to dark mode depending on the browser preference, +If you don't want the theme to automatically switch to dark mode depending on the browser preference, you can disable dark mode by adding the `light-mode` class to the html-tag in the header template: ```html @@ -38,7 +41,7 @@ The same can be done to always enable dark-mode: ``` -**This only works if you don't use the dark-mode toggle extension.** +@warning This only works if you don't use the dark-mode toggle extension. ## Choosing Sidebar Width @@ -62,64 +65,58 @@ TREEVIEW_WIDTH = 335 ## Formatting Tables -By default tables in this theme are left aligned and as wide as required to fit their content. +By default tables in this theme are left-aligned and as wide as required to fit their content. Those properties can be changed for individual tables. ### Centering Tables can be centered by wrapping them in the `
` HTML-tag. -**Example:** - -```md -
- -| This table | is centered | -|------------|----------------------| -| test 1 | test 2 | - -
-``` - -**Result:** +
+ +- Code + ```md +
+ | This table | is centered | + |------------|----------------------| + | test 1 | test 2 | +
+ ``` +- Result +
+ | This table | is centered | + |------------|----------------------| + | test 1 | test 2 | +
-
+
-| This table | is centered | -|------------|----------------------| -| test 1 | test 2 | -
### Full Width To make tables span the full width of the page, no matter how wide the content is, wrap the table in the `full_width_table` CSS class. -@warning Apply with caution! This breaks the overflow scrolling on small screens! - -**Example:** - -```md -
- -| This table | fills the full width | -|------------|----------------------| -| test 1 | test 2 | +@warning Apply with caution! This breaks the overflow scrolling of the table. Content might be cut of on small screens! + +
+ +- Code + ```md +
+ | This table | spans the full width | + |------------|----------------------| + | test 1 | test 2 | +
+ ``` +- Result +
+ | This table | spans the full width | + |------------|----------------------| + | test 1 | test 2 | +
-``` - -**Result:** - -
- -| This table | fills the full width | -|------------|----------------------| -| test 1 | test 2 | - -
- - diff --git a/doxygen-awesome-tabs.js b/doxygen-awesome-tabs.js new file mode 100644 index 0000000..8e725b2 --- /dev/null +++ b/doxygen-awesome-tabs.js @@ -0,0 +1,70 @@ +/** + +Doxygen Awesome +https://github.com/jothepro/doxygen-awesome-css + +MIT License + +Copyright (c) 2023 jothepro + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +*/ + +class DoxygenAwesomeTabs { + + static init() { + window.addEventListener("load", () => { + document.querySelectorAll(".tabbed:not(:empty)").forEach((tabbed, tabbedIndex) => { + let tabLinkList = [] + tabbed.querySelectorAll("li").forEach((tab, tabIndex) => { + tab.id = "tab_" + tabbedIndex + "_" + tabIndex + let header = tab.querySelector(".tab-title") + let tabLink = document.createElement("button") + tabLink.classList.add("tab-button") + tabLink.appendChild(header) + tabLink.addEventListener("click", () => { + tabbed.querySelectorAll("li").forEach((tab) => { + tab.classList.remove("selected") + }) + tabLinkList.forEach((tabLink) => { + tabLink.classList.remove("active") + }) + tab.classList.add("selected") + tabLink.classList.add("active") + }) + tabLinkList.push(tabLink) + if(tabIndex == 0) { + tab.classList.add("selected") + tabLink.classList.add("active") + } + }) + let tabsOverview = document.createElement("div") + tabsOverview.classList.add("tabs-overview") + let tabsOverviewContainer = document.createElement("div") + tabsOverviewContainer.classList.add("tabs-overview-container") + tabLinkList.forEach((tabLink) => { + tabsOverview.appendChild(tabLink) + }) + tabsOverviewContainer.appendChild(tabsOverview) + tabbed.before(tabsOverviewContainer) + }) + }) + } +} \ No newline at end of file diff --git a/doxygen-awesome.css b/doxygen-awesome.css index 3961e82..a135ede 100644 --- a/doxygen-awesome.css +++ b/doxygen-awesome.css @@ -2228,7 +2228,8 @@ div.memproto::-webkit-scrollbar, .contents .center::-webkit-scrollbar, .contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody::-webkit-scrollbar, div.contents .toc::-webkit-scrollbar, -.contents .dotgraph::-webkit-scrollbar { +.contents .dotgraph::-webkit-scrollbar, +.contents .tabs-overview-container::-webkit-scrollbar { background: transparent; width: calc(var(--webkit-scrollbar-size) + var(--webkit-scrollbar-padding) + var(--webkit-scrollbar-padding)); height: calc(var(--webkit-scrollbar-size) + var(--webkit-scrollbar-padding) + var(--webkit-scrollbar-padding)); @@ -2242,7 +2243,8 @@ div.memproto::-webkit-scrollbar-thumb, .contents .center::-webkit-scrollbar-thumb, .contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody::-webkit-scrollbar-thumb, div.contents .toc::-webkit-scrollbar-thumb, -.contents .dotgraph::-webkit-scrollbar-thumb { +.contents .dotgraph::-webkit-scrollbar-thumb, +.contents .tabs-overview-container::-webkit-scrollbar-thumb { background-color: transparent; border: var(--webkit-scrollbar-padding) solid transparent; border-radius: calc(var(--webkit-scrollbar-padding) + var(--webkit-scrollbar-padding)); @@ -2257,7 +2259,8 @@ div.memproto:hover::-webkit-scrollbar-thumb, .contents .center:hover::-webkit-scrollbar-thumb, .contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody:hover::-webkit-scrollbar-thumb, div.contents .toc:hover::-webkit-scrollbar-thumb, -.contents .dotgraph:hover::-webkit-scrollbar-thumb { +.contents .dotgraph:hover::-webkit-scrollbar-thumb, +.contents .tabs-overview-container:hover::-webkit-scrollbar-thumb { background-color: var(--webkit-scrollbar-color); } @@ -2269,7 +2272,8 @@ div.memproto::-webkit-scrollbar-track, .contents .center::-webkit-scrollbar-track, .contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody::-webkit-scrollbar-track, div.contents .toc::-webkit-scrollbar-track, -.contents .dotgraph::-webkit-scrollbar-track { +.contents .dotgraph::-webkit-scrollbar-track, +.contents .tabs-overview-container::-webkit-scrollbar-track { background: transparent; } @@ -2307,7 +2311,8 @@ div.memproto, .contents .center, .contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody, div.contents .toc, -.contents .dotgraph { +.contents .dotgraph, +.contents .tabs-overview-container { scrollbar-width: thin; } @@ -2440,3 +2445,78 @@ a.anchorlink:hover { h2:hover a.anchorlink, h1:hover a.anchorlink, h3:hover a.anchorlink, h4:hover a.anchorlink { display: inline-block; } + +/* + Optional tab feature +*/ + +.tabbed ul { + padding-inline-start: 0px; + margin: 0; + padding: var(--spacing-small) 0; + border-bottom: 1px solid var(--separator-color); +} + +.tabbed li { + display: none; +} + +.tabbed li.selected { + display: block; +} + +.tabs-overview-container { + overflow-x: auto; + display: block; + overflow-y: visible; +} + +.tabs-overview { + border-bottom: 1px solid var(--separator-color); + display: flex; + flex-direction: row; +} + +.tabs-overview button.tab-button { + color: var(--page-foreground-color); + margin: 0; + border: none; + background: transparent; + padding: var(--spacing-small) 0; + display: inline-block; + font-size: var(--page-font-size); + cursor: pointer; + box-shadow: 0 1px 0 0 var(--separator-color); +} + +.tabs-overview button.tab-button .tab-title { + float: left; + white-space: nowrap; + padding: var(--spacing-small) var(--spacing-large); + border-radius: var(--border-radius-medium); +} + +.tabs-overview button.tab-button:not(:last-child) .tab-title { + box-shadow: 8px 0 0 -7px var(--separator-color); +} + +.tabs-overview button.tab-button:hover .tab-title { + background: var(--primary-color); + color: var(--page-background-color); + box-shadow: none; +} + +.tabs-overview button.tab-button.active { + color: var(--primary-color); + box-shadow: 0 1px 0 0 var(--primary-color), inset 0 -1px 0 0 var(--primary-color); +} + +@media (prefers-color-scheme: dark) { + html:not(.light-mode) .tabs-overview button.tab-button:hover .tab-title { + color: var(--page-foreground-color); + } +} + +html.dark-mode .tabs-overview button.tab-button:hover .tab-title { + color: var(--page-foreground-color); +} \ No newline at end of file diff --git a/doxygen-custom/header.html b/doxygen-custom/header.html index 1fc73c5..7f37e6f 100644 --- a/doxygen-custom/header.html +++ b/doxygen-custom/header.html @@ -29,12 +29,14 @@ + $treeview $search diff --git a/img/theme-variants.drawio.svg b/img/theme-variants.drawio.svg index a8682dd..f905d7d 100644 --- a/img/theme-variants.drawio.svg +++ b/img/theme-variants.drawio.svg @@ -1,4 +1,4 @@ - + @@ -8,13 +8,18 @@
- 1. Base Theme + + + 1️⃣ + + + Base Theme
- 1. Base Theme + 1️⃣ Base Theme @@ -25,13 +30,18 @@
- 2. Sidebar-Only Theme + + + 2️⃣ + + + Sidebar-Only Theme
- 2. Sidebar-Only Theme + 2️⃣ Sidebar-Only Theme @@ -233,7 +243,7 @@ - Viewer does not support full SVG 1.1 + Text is not SVG - cannot display